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You've created ihe perfect piece, now you're looking for a good sen ice bureau for output You want 
quality, but ii must be economical. Finally, and most important.. .you have to find a service bureau thai 
recognizes your AMIGA file formats. Your search is over. Give us .1 call! 

We'll imajiesci your AMIGA graphic files to RC Laser Paper or film al 2450 dpi (up 10 154 Ipiiat a 
extremely competitive cost. Also available at competitive cost are quality Dupont ChromaCheck IM 
color proofs of your color separations/films. We provide a variety of pre-press sen ices for the desktop 
publisher. 

Who are we? We are a di\ ision of PiM Publications, the publisher of Amazing Computing for the 
Commodore AMIGA, We have a staff that rvully knows the AMIGA as well as the rigid mechanical 
requirements of printers/publishers. We're a perfect choice for AMIGA DTP imageseiUng/pre-press 
services, 



\\< support nearly even AMKiA ftniphic iv DTP formal as well as most Macintosh™ graphic/DTP 

formats. 

I or v'" ifi* format information, please call. 



For more information call 1-800-345-3360 

Just ask /'" il»- service bureau representai 



printf ("Hello") ; 



print "Hello" 



JSR printMsg 



say "Hello" 



writeln( "Hello 



// 



VI hal «>\ er language you speak. M's IIMI 

provide* » platform for both gaining insight 

and shoring information on Its most 

iiuio\ ;ii i\ <• implementation for the Amiga. 

Why not see if >our latest progrn mining 

endentor ean help a fellow Amiga user 

expand ti|ion his or her voeabulary? To lie 

eonsidered for publieation in AVs IIMI. 

submit your teehnienlly oriented arliele 

(both hard eopy & disk) to: 

\< s TECH Submissions 

I'i.M Publications, Iru 

< >ne Currani Place 

I. ill River. MA <>2~>2 
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Startup-Sequence 



The Amiga Market 

I ,im often asked by fellow Amiga devel- 
opers what I believe is the current state of the 
Amiga market I appreciate the question, but I 

am not certain which one of my opinions I 
should give. When asked I am reminded of the 
story of the five Wind men who were told to 
describe an elephant by fed Hath man went to 
a portion ot the elephant and made .1 judge 
ment of what the animal was like by what he 
fell 

"ll i* like a snake," said the man who was 
holding the trunk of the elephant. 

No,ll is as solid and as stable as a tree." 
said the second man braced against the 
elephant's knee 

"YOU are both wrong The elephant is .1 
Luge flying animal with great wings.'' gild B 
man feeling the elephant'*, large flexible Ban 

I feel an animal as big and solid as a 
wall," said the man who was feeling the 
elephant's side. 

fhisbeastislikeacamelora great horse." 
said the blind man who had been placed on the 
back of the elephant's neck. 

While these descriptions were not correct, 
the) wen not completely wrong The blind 
men suffered from a problem of perspective. 
They knew only what they were allowed to feel 
.m>\ experience. They judged what they per- 
ceived based on their limited ptfSpCl live Their 
only fault was that they did not bother to check 
the elephant further. Their final divisions were 
based on incomplete information 

Many Of us view the Amiga market from 
the same manner in which the blind men de- 
scribed their elephant II we do not see adver- 
tising Ul the l S we assume that there is no 
advertising and that Commodore is abandon- 
ing the Amiga It haidly crosses our minds that 
then-arc othcradverti-ing mediums than those 
we see. When members ofCBM tell us that they 
are advertising in vertical markets and profes- 
sional related areas, we complain thai they .ire 
not doing more 

However, this scenario is currently play- 
ing in Commodore markets throughout the 

world. While Amiga users m North America 

fed that the Amiga is not being seen as the 
potential home/gaming computer suited for 
the commercial market as well as the profes- 
sional arena, L'.K developers are upset that the 
Amiga is not being utili/.-d .is .1 pro fe s si onal 
platform, but merely as a game machine. 

This fact is so entrenched in the psyche ot 
people in the U.K. marketplace thai I was cur- 
rently told by a major executive ot an English 
company that the Amiga was used only lor 



games and that if anyone wanted to do any- 
thing serious with a computer, they would get 
.in MS-D06 machine 

I walked into an outlet of a major electron- 
ics company in Europe and found the Amiga 
prominently displayed in an area designated 

mputer gaming Across the room, where 
the men professional systems were, there were 

no Amiga*. |ust MS-DOS machines. However. 
before anyone raises the point thai this is the 
same in (he U.S. due to the low prices for MS- 
DOS machines, I must tell you that the MS-IX1S 
machines were selling for twice as much if not 
more than they are priced in the US. In addi- 
tion, there were very few advanced MS-DOS 
units available 1 found few 386 models and 
none of the 486 machines thai have been selling 
inexpensively in the L.S for some time now. 

There is a lot to the point that at leas! the 
Amiga was available in a mass market setting 
and that the machine has established a solid 
footing However, if people disregard the 
computer's better features, what future will the 
Amiga have' 

IromSydriev 10 I oronto, everyone has a 
different idea as to what the Amiga can do and 

how it should be marketed. While this poses a 

problem for Commodore International, it has 
offered a mother lode of opportunities for the 
restol us While every one is pulling indifferent 
directions and establishing different markets 
for the Amiga, they have created a vast array of 
product openings 

With each new market, there is a need for 
more products What about a word processing 
database, or spreadsheet product for the Euro- 
pean market' It would be brightly colored, its 
features would be small but quickly under- 
stood, and it might even have arcade qualities 

built into it It would be priced to sell competi- 
1 1 vel y with the better games on the market, and 
it would make money. 

In the US, look to see who is buying 
Amiga systems and develop more games for 
them While I am assured by our staff Statisti- 
cians that a great deal of professional systems 
are also being used by people who love to play 
games, I still would want to see a game that 

would Interest people on a new lev. -lot sophis- 
tication so that it would not be confused with 
the more rapid arcade-style games currently 
available. 

How about an entertainme nt p a ckage thai 

made an arcade or strategy game out of video 

editing or sound manipulation? Why not use 

the interests of your market to create a better 

im' 



CDTV Ls a masterful piece of hardware 
and Commodore is sincerely doing a better job 
of selling it than Phillips is doing in pushing CD 
Interactive Everyone .igreesth.it the platform 
is not the problem, but there needs to bealdller 
piece of software to sell 'the machine Isn't this 
the market iv ear.- in 1 1sn't this all we need to be 
told to create the breaks we want ' 

Opportunity rarely comes hopping into 
the room with a bell around its neck Opportu- 
nitv sometimes occurs with the close scrutiny 
of a market, process, activity, or situation that 
eventually vtelds a new and better idea of at- 
taining 1 goal Opportunity can often occur 
with a single blind leap ol inspiration, which I 
believe is the subconscious mind doing all the 
hard work while we end up taking the credit 
But, no matter how the opportunity develops, 
it must be recognized for v% hat it is 

IV- realistic, you ma) .lis, 01 ei only a small 
opportunity Ik- thorough, it may be an oppor- 
tunity that has already been fulfilled Be tena- 
cious, it you find it is something that could be 
done and you could do it — tear into it and gel it 
done 

li vou have a practical application that 
you believe could set the world on fire, then 
develop it. Don't wait for Commodore toes tab 
lish the market Commodore sells a platform 
that is called the Amiga. It is a great machine 
with a lot ol capability But the successes in this 
marketplace have not happened because fliej 
have Waited for Commodore or any computer 
platform manufacturer to provide the market 
They havvoccurred when individuals and com- 
panies have recognized the market for what it 
can become and have developed applications 
and tools lo work within this new area 

Even with the mass marketing of MS-DOS 
machines and the flashy words from Apple- 
Computer. I still have not seen the level of 
opportunity that I sec In today's Amiga mar- 
ket — not only for the U.S. and Canada, but for 
the entire world We are no longer a closed 
market. Our opportunities he all around the 
globe ll only requires that we understand the 
entire elephant and not just the part we have 
hold of today. 



Sincerely, 



M 



Don Hicks 
Managing Editor 
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PCX Graphics: 

Now You See Them! 



fry Gary L tail 



Do you need an extra piece of dip art for your latest newslet- 
ter? I low about some color artwork for your" collection* 

I ake a look in the MS-DOS section of your favorite bulletin 
board system and you will probably find .1 large selection ol 
graphics called PCX Hies. Of course, this may present a problem 
because PCX files are designed to be viewed (01 created or 

changed) with PC /tomffrntsft, an MS-DOS program Or is it really 

.1 problem? 

You can vie*, anj *-bit graphics fileon your Amiga it you do 
a little research and a little programming. The accompanying 
program, ShowPCX, demonstrates how to read and view PCX 
files on the Amiga 

What Are PCX Files? 

PCX files are graphics files which have been stored in a 
format devised by /Sift (Marietta. Georgia) when it 1 reeled PC 




Paintbrush, an all-purpose MS-DOS paint program. This file 
format has become a "standard" in the MS-DOS world, and most 
desktop publishing software provides PCX importing capabili- 
ties. In fact, many Manner-, output graphics in the [>CX format, 
and both Apple and MS-DOS graphics programs often make use 
of that capability. That's good for ti> because it mean*; there is a 
tremendous quantity of artwork out there waiting to be down- 
loaded. 

The l*CX file format allows up to 256 colors to be used at once. 
To keep it simple, however, we will limit ShowlX.X to 16 colors. 

But there are plenty of PCX files out there which use fwo colors 

(one hitplane) and 16 colors (four bitplanes). so you will have 
plenty to see. 

Reading a PCX File 

In order to read a l*CX file and display it on the Amiga, we 
need to follow this procedure: 

1 . Open the PCX file and read the header 

2. Open a SuperBilMap window. 

3. Unpack a line of pixels from the file and store it in 
the SuperBitMap. 

4. Repeat Step 3 until all lines have been read 

5. Open a window and display the file. 

6. Allow user to scroll through the window and quit. 
Almost any programming language can be used to read and 

display PCX files as long as you can access the Amiga's Intuition 
functions. This example uses the C language. 

The PCX Header 

All PCX files begin with a 128-byte header. This header 
contains all the information necessarv to read the hie 

ShowPCX reads the header and stores the information in a 
structure we call pvx fulr 



This sompto is actually consists of 16 colors. 
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struct pex .Mr 



unsigned char manufacturer; 

unsigned char version; 

unsigned char encoding; 

unsigned char bits per pixel; 

unsigned int nin; 

unsigned lot ynin; 

unsigned Int xnax; 

unsigned int yaax; 

unsigned int hres; 

unsigned int vres; 

unsigned char palette 148]; 

unsigned char reserved; 

unsigned char color planes; 

unsigned int bytes_per„line; 

unsigned int palette_.type; 

unsigned char filler[58]; 



h 



Ihe slructure members we will need to use .ire: 

manufacturer— This unsigned char must equal 10. or it is not 
a KX rile. 

uruixymin—lriese integers identify the upper left comer of 
the image (with 0,0 being ihe upper left corner of the window ) 

xmax, ymax — These Identify the lower right corner. 

pa!ette|48l— Color information is stored in these 48 bvtes 
More about this Liter. 

color_planes — This member will tell you the number of 
colors used lo create the image. Since we get two colors tor each 
bitplane, this number can be up to four, because we are limiting 
ShowFCX to 16 colors 

bytes_per_line — ShowPCX needs to know this so it knows 
how much "uncompressed" information to expect for each line of 
pixels in the image. 

The other parts of the structure are either filler or are unnec- 
essary for our purposes. 

The Program 

[Stew that we understand the importance of the PCX header. 
let's look at the program. Much of the initial code in ShowPCX.c 
IS used simply to lay the groundwork for the program. We 
idenhu the Structures we arc going to use, the types of variables 
which will be necessary, list the lunctions which arc to follow, and 
create a simple "quit* menu. 

\- it ts written. Show PCX can be run from the CI I by typing 

ShowPCX graphicsfile 

The program checks to see if your I'CX file exists and then 
attempts to open it. 



If everything is OK. the program then calls the function 
readheaderf). The first step in this process is to read the first byte 
if it does not equal HI, then it is not a PCX file and we exit with a 
brief message to the user. Assuming thai the first byte equals 10, 
we continue to read the rest of the header variables, 

By the way. you will notice a function in Show I'CX called 
readintl) Intel processors like those used in the IBM I'C and 
clones store short integers "backwards." In an MS IK'S file, the 
least significant b) te comes lirst. followed b\ the most significant 
b> te. ■) 011 can see that in readintfl WC read both bytes, shift Ihe bits 
in the second byte to the left 8 bits and then "( )R" them to get one 
16-bit number we can use. It makes you appreciate owning an 
Amiga, doesn't il? 

Alter reading the header, we need to check the color_plancs 
member ol pc\. hdr. If this number is more than 4, you have 
probably found a 256-color PCX file and ShowPCX won't read it 
If the variable is 4 or less, we are in business! 

We then decide if we need a lo-res screen or a hi-res screen 
and assign values to screenwidth, screenln-ight. windowwidth, 
and wmdowheight — all of which should need no explanation. 

Using a SuperBilMap Window 

After opening the appropriate libraries, we can then set up 
for reading the actual PCX graphics data 

Most PCX files will not fit bit-lor-bit on an Amiga screen. 
I he) are apt to be tint high or too wide or both Fortunately, the 
Amiga comes prepared for Ihis. We can open a window which is 
actually larger than the screen and we can scroll the image to 
make it visible. This is called a SuperBilMap window, and the 
hard part-, an- taken can- of by Intuition. (Note: For more about 
SuperBilMap windows, see "Scrolling Through SuperBilMap 
Windows" by Read Predmore in Ama/ing Computing, V4.1, 
January, 1989 I 

We need to store the I'CX data in our own bitmap and then 
open a window which uses that bitmap. The only limitation on 
the size and depth of the bitmap is the amount of memory in your 
Amiga. 

Show I'CX creates a bitmap by calling the function openbmf). 
Since the PCX header told us the width, height, and number of 
color piano necessary, we teed that information to Intuition's 
ImtBitMapO function. If you have enough memorv, the Amiga 
handles all the dirty work. If there was, 1 problem, we again notify 
the user and exit from the program. 

Time for a brief review So far. we have opened a PCX file, 
read Ihe header, and created an empty bitmap. We have not 
opened a screen or window, nor have we read even the first byte 
ol data from the file. So let's get going. 

Reading the File 

For a one-bitplane image (two-color), the program calls the 
function domonof). The function docolorO is called for a four- 
bitplanc image. Both work alikeexcept that docolor( ) must handle 
tour limes as much data. 

A two-color line of pixels is read with Ihe function readlinef). 
■si net- each bit of each byte is either "on" or "off," tt [seasy to read 
a line ot pixels Here's how: 

PCX tiles use a crude form of compression called run-length 
encoding The image is compress,,! by counting repeating bvtes 
If tin- top two bits of a byte are both 1, then the byte is a "count" 
byte After disregarding the top two bits, the remaining value is 
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the number of limes the following byte is repeated. The program 

code looks like this 



k 




1 






c ■ fgetc(eptr); 




iff ic i 0x21); 




1 




1 ■ tC • 0x3f); 




c ■ ffletc(sptr); 




while (i-J 




I 




Pltn] ■ 




♦♦ni 




I 




) 




else 




( 




pltn] - c; 




*.n; 



c; 



/• Get a byte froa the file •/ 
/• Are the top two bits set? '/ 

/■ Get rid of the top two bite V 
/• Get the next byte from file •/ 
/• -Run" the byte •/ 



/• Else store the original byte •/ 



) 
while(n < bdr.bytes_per_line); 

/' Continue until the line is full 



A color line is very similar except lh.it the four color planes 
are treated as one long line (or each row of pixels. The 
readcolorlineO function continues to read and "run" bytes until 
it has read four limes the number of bytes we expect to find in a 

line. 

For two- or 16-Color images, the lines ot pixels are Stored in 
the SuperBitMap. 

Let's Take a Look! 

I -inally, we are ready to put something on the screen! A call 
to the (unction openwinO opens a screen and a window. It also 
creates QUI custom menu strip. 

We also need to set the Amiga's colors to those used in the 
PCX file we are to view. We already read the color palette values 
from the PCX header and these are transferred to the screen with 
the function getpallette(). 

These values were stored in hdr.palette| |. We have 48 bvtes 
of data— one byte for each red. green, and blue value for four 
bitplanes. We can go ahead and set our colors using all 48 bytes 
even if we are dealing with a two-color image. 

At this point, there should be an image on the screen. But, as 
I mentioned earlier, a PCX image may be larger than the Amiga 
screen. That's why we used a SuperBitMap, remember? 

To handle this, ShowPCXx calls the functions getactionQ, 
getmessagc(),and getevent(>. If the user moves the mouse pointer 
near the edge of the screen, the program will attempt to scroll the 
image inmatdirecHon.Thisisallexplained in the source codeand 
should be easy to follow. 



To exit the program, the user chooses "Quit'' from the menu. 
At that point, the program cleans up by closing everything it 
opened Afl a final touch, ShowPCX prints out the values from the 
header to the screen. 

There's More 

Because of space limitations, ShowPCX is pretty simple. But 
With a little work, any aspiring programmer can turn it into a 
masterpiece. One idea for improvement is adding the ability to 
handle 256-color PCX files. More "user friendliness" would also 

be nice,along with theability to run the programfrom Workbench. 
Another idea is a routine to convert the images to III 

Well, what are you waiting for? just be sure to share your 
results with the rest of us. 



For more information on the PCX file format, see the following: 

Translating PCX Files" by Kent Quirk, I>. Dobb's Journal, 
August. 1989. 

Bit-Mapped Grapht, - b\ Steve Rimmer, Wmdcrest (Tab 
Books), 1990. 
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■bowrei >c 

By Gary L. rale 

Allow* Aauga to dlaplay J -color <ona plana) and 16- 
color (lour planaa) .pcx graph ica fllaa craatad with PC 
Paintbruah IZSoft, Marietta, QA| . 



■lncluda <exac/typea.h> 

■Includa < Intuit ion/ Intuit Ion. h> 

■lncluda < graph lea/ gf xmacroa. h> 

■includa <atdlo.b> 

■lncluda <atdllb.h> 



pcx.h 

Contalna definition of 



a pcx haader . 



itruct pcx_hdr 
i 

unaignad 






char 


aanufacturarj 


unalgnad 


char 


varaloni 


unaignad 


char 


ancoding.- 


unalgnad 


char 


blta par pixal; 


unaignad 


lnt 


xaln; 


unalgnad 


int 


vminj 


unalgnad 


lot 


naax; 


unalgnad 


int 


ynax; 


unalgnad 


lnt 


hraa; 


unalgnad 


lnt 


vraaj 


unaignad 


char 


palatta(481; 


unalgnad 


char 


raaarvadj 


unalgnad 


char 


color planaa j 


unaignad 


lnt 


bytea par Una 


unaignad 


■ :.•_ 


palatta^typai 


unaignad 


char 


flllar(Sa)i 



h 



atruct 
at rue t 
atruct 
atruct 
atruct 
atruct 
atruct 
atruct 
atruct 
atruct 
atruct 
atruct 

PILE • 



/*•• Othar atructuraa va will naad 
IntultionBaaa 'Intuit lonBaaaj 
GfxBaaa *OfxBaaa; 
LayaraBaaa ■LayaraBaaaj 
IntulMaaaaga ••aag, •GetHagf ) i 
HawScraan NawScraam 
Scraan 'ulntcratn; 
HewHindow KawNlndowt 
Window "malnwlndow; 
Bit Hap *arybiiaaapi 
pcx Mr hdrj 
RaatPort "rportj 
VlawPort "vportj 
aptr. *fopan<)i 



unalgnad char aourca[1381. k. c. -t. pHSl2].- 

unalanad int gtaop. xtaaap. rinaltanx), quit, a, 1. n, u. v. 

w. x, yi 
unalgnad long claaa. code; 
abort xacroll. yacroll. xnaxacroll. ynaxacroll. xpoa, ypoa, 

acraanwidth. acraanhalght. acreendapth. 
wlndowwldtb. 

wlndowhaigbt i 



". 



/••• 


Functlona wa will 


void 


dcatonol ) j 


void 


docolorl) ; 


void 


i a ad ll no( ) ; 


void 


readcoloriineu ; 


void 


gatpalattat) t 


void 


doacrolU), 


void 


raadhaadarO : 


void 


prlnthaadarO i 


void 


raadlntd j 


void 


gatactlonl) i 


void 


gataaaaaga<) , 



void gatavantO; 

void opanltbaOi 

void opanhnO; 

void opanwin ( ) i 

void claanupOi 



atruct 

I 

1 1 

atruct 
{ 



atruct 

1 



Sat up mou 
IntulTaxt qulttaxt - 

0. l.JAw.l.CHEClTWIDTH. 0. MULL. "Quit-. KULL 

MaouXtaa gultitaa . 

NULL, 0.0. 75. 10.ITBKTEXTIHIOHBOXI ITEMIHABLID. 0. 

( APTmjiciu It text, HULL, HULL. HULL. NULL 

Hanu gultmanu • 

BULL, 0,0, 75. l,I0SHUl»lABL*D.-PE03act-.4gultltaai 



)l 



tint) 



aaln(argc.argv) 

lnt argc] 
char "argv [ 1 ; 

t 

prlntf (-\nShowPCX \n"l j 

printf(-By Gary L. Palt\n\n-»j 

prlntf (-ShowPCX dlaplaya a PCX graphica 

Eil«.\n\a")j 

/••* If naceaaary, abow uaar how (9 run progrtfl. 
•••/ 

if large < 2) 

( 

prlntf("\nTo run. uaa, ShowPCX 
grapblcf lla.pcx\n\n")i 

autlt|0)| 

) 

• laa /*** Otharwiaa. uaar baa dona it right. 



'/ 



( 

atrcpy(aource.atgv(l) ) 1 
) 

/••• Add -.pcx- to fllanaxat if oaadad •••/ 
If (atrchrlaourca. *.'| >• WOTAl 



atrcat (aourca, ".pcx") 1 



/'•' Opan fila •••/ 

ifdtaptr - fopan(aourca."rb")M 

1 

prlntf (-sowtV: Can't find/opart \a. \n*. aourcal 1 

•alt (Q)j 

) 



raadhaada r I I ; 



Oo taad haadac Information, 



/••• Kuat not ba acre than 16 colore ""•/ 

lflbdr. color planaa > a) 

1 

prlntf ("Mrrbla (lit baa aora than 16 colotal\a-)i 

claanupl ); 

1 



/■■• Will It fit in a loraa 

lflhdr.xmax «a 330) 
1 
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iffhdr.ymax <- SOD) 

1 

■craanvldth ■ hdr.xaax . lj 

ncraonhalght ■ hdr.ymax • 1; 

/*•• Scr«on nuat be at laaat 320 plxale wida •••/ 

irihdr.KUx < 330) 

acraanvldth • 330] 

acraandapth « bdr. color pi* 



windowwldth ■ hdr.xnax • lj 
wlndovhaight ■ hdr.ymax . I; 



-lj /••• Prohibit acrolUng •••/ 
-ll 



< scroll 
yaaxacroll 

/••• Should It b« hlrBB? ■••/ 

lt<hdr.xMX > 330) 

( 

acraanvldth ■ hdr.xatax • 1; 

ecraenhatght - ndr.yna* • 1; 

/•** Set nun must b* at laaat 640 pixels -Ida ■• 

iffbdr.XMax < 640) 

acreenwldth • 640 j 

acraandapth - hdr. color fltatu 



windowwldth ■ hdr.xmax . 1; 

wlndovhaight ■ hdr.ymax • 1; 

/••• Don't go nor* than 1034 plxale high •••/ 

if (wlndowhaight , 1024] 

windowheigbt - 1034; 

/••• P«tenUw max uount of ecrolllng aliased 

xnexacroU ■ windowwldth - 640; 

If (XMxacroll < 0) 

xmaxacroll ■ 0; 

yaaxacroll - wlndovhaight - 400; 

if (ynexacroU < 0) 

y»*Mcreu ■ 0) 



j 



openlibaO; 

openbaM); 

iflhdr. color plan.. .. 



return* 

/"•" Otbarwiae. copy line Into the bitmap. 
for(a ■ 0; a < hdr. bytea. per line; «..) 



■ybl 

X« • J 

> 

I 



->Planea|0J [x] - pl[al; 



dc-color ( I 
Reada 16-color pcx file Into bitmap ■eaaory. 
HOTti Z Soft uiei An Interleaved format for color laagea. 



void docolorO 

( 



u ■ Oi 

v - 0; 

v . 0; 

x . 0. 

forly i 

1 

/■•• oan Una of data from fila. •••/ 

/••• Actually, you will gat a 'acan Ho*- of 



0; y < windowheigbt; y..> 



data... 
Una 



i.., 



which will include anough data to fill a 

io aach bit plana. •■■/ 
readcolorllne{) I 



If it'a lor 



l> l 



If it'a ■onochroa* 



l(<n « 4 • hdr.bytaa par. Una) /•' 

rat urn/ 

a . 0, 

whilata < (n - 1)) 



/*** Stora a Una of data In flrat bitplana •••/ 

forli • Oi i < hdr.bytaa par Una; i*+] 

I 

mybltaap->plsnea|0] [u] - pile); 



< 

doatono I ) i 

) 

alaa if (hdr.color_planaa « 4) 



color •••/ 

1 



" If it'a 16- 



vold 
{ 



docolor ( ) j 

> 

alaa 

< 
cleanup! )i 

) 

opanwinl); 

gatpalattaO; 

gatactionO; 

print haadar I ) ; 

cleanup! I; 



doMonoO 

Raada ■onochrcaka pcx fila Into biuaap Bwnory. 



(1 



x • Oi 

forly - 0; y < wlndowhaight; y..) 

( 

raadllnaO; /••• cat a Una of data fro*. Ilia. 



if In < hdr.bytaa par. Una) 



/• 



If lt-a tor 



) 

/*" Stora a Una of data in aacond bitplana •"•/ 

ford - 0; i * hdr.bytaa per.Unei 1..) 

( 

■Ybitaap->Plana*(l) [v| - pita); 

• •v; 

• •a; 
I 

/••• Stora a Una of data in third bitplana •••/ 

ford - 0; i < hdr.bytaa par Una; i..> 

( 

myblt«ap->Planaa[3]Iw] . pl|a)j 

• •wi 

• •aj 
) 

/■•• Stora a Una of data in third bitplana •••/ 

forli ■ 0i 1 < hdr.bytaa par Una; i..) 

( 

■ybltaap->plaoaa[31 Ix! - pl[a)i 

• ♦x/ 

• •aj 
1 



readlinaO 

ftaad and daccaapraaa a aingla Una froai fila. 

Oae thla function for monochrome (Ilea. 



void raadllnaO 
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0; 
0: 



do 

( 

c - fgatc(aptr); 



/«•• Oat a byta •••/ 
If It'a * run of bytaa fl-ld 



if He fc OxcO) « OxcO) 

I 

1 - (c fc 0x3f)j /••• AMD off tha high bita ■••/ 

c ■ fgatc(aptr)j /*"' Gat tha run byta 



whlla(l-) 

( 

pi (III - c; 

**m 
) 
I 
•lH 

< 

p»[n| ■ ci 



/■•■ Run tha byta 



char rad. graan. blua; 
■ a 0) 

ford - 0; 1 < 16; l..> 
< 

/""• Shift aach valua right four bits •••/ 
rad • hdr.palattalaj >> 4; 
a-. j 

graan ■ hdr .palatta[a] >> «: 
•••I 

blua ■ hdr.palatta(a] >> 4; 
• ••j 

SatROB4tvport.i. rad. graan. blua) i 
) 
) 

/ ........ 

doacroll ( ) 
Takaa Information fro* gatactioo function and 
acraen ... If poaalbla. 



■ova lnaga on 



void 
< 



/*** Klaa atora tha original byta 



doacroll (I 

'•** If wa'ra alraady at laft adga, don't nova. 



• »nj 

1 

) whilatn < hdr.bytaa par. Una) 



If ( (xacroll . xpoa) 
rat urn. - 



Qi 



raadcolorllna( ) 

Haad and dacoapraaa 16-color Una frcai flla. 
Thla function will raad an antlra 'acan Una' of data. It 
will contain tha data to fill all four bltplanaa for ona 
color Una on tha acraan. 



void raa-dcolorllna() 
1 

B a 0] 

1 ■ Oj 

I 

c - fcatc(aptr); 



/••* II It 1 

OxcO) 



Cat a byta ••■/ 
a run of bytaa fiald 



•••/ 



ift<c k OxcO) 

( 

1 - (c a 0x3f); /••• AHD off tha high blta •••/ 

c ■ fgatciaptrd /••• Oat tha run byta 



/••• Run tha byta 



whil.ii 


1 


( 




Pllnl - 


c: 


• •n; 




) 




1 




alaa 




I 




PUn J - 


ci 



1 



llaa atora tha original byta 



• •nj 

i 

) whlla(n < (4 • hdr.bytaaj>ar_llna))j 



/ 

gatpalatta( I 
Raada 16 ROB colora frcai palatta and aata acraan colors. 
It'l okay to uaa thla for ■onochroaia fllaa. too. but only 
tha flrat two colore will bo uaad. 



am 



void 



void gatpalattal) 



/••• If wa'ra alraady at top. don't aove. •••/ 

lfltvacroll > ypoa) < 0) 
rat urn; 

If (xacroll I- 0) 

( 

/"• If wa'ra at right adga, don't mova. •••/ 

lfUxpoa . xacroll) > xaaxacroll) 

( 

xacroll ■ 0; 

1 

alaa 

( 

xpoa - xpoa • xacrollj 

) 

} 

lflyacroll 1- 0) 

( 

/••• If wa'ra at bottom, don't nova. "•/ 

It < (ypoa . yacroll) > yaaxacroll) 

( 

vac roll ■ 1 

) 

alaa 

{ 

ypoa - ypoa . yacroll. • 

) 

» 

/••• If wa'va aada It thla far. go ahaad and acroll 

acraan. •■•' 

ScrollLayar(Minwindow->WL*yar->LayarInfo. 
■a lnwlndow->HLayar. xacroll. yacroll) ; 



raadhaadar { ) 
Raad hoadar Information from baglnning of flla. 

raadhaadar ( ) 

printf t-\n*aading PCX flla ... Plaaaa walt.\n-)i 

f aaak(aptr.OL.O) .- 

/••• Haka aura thla la a .pcx flla. **•/ 
fraadUehar ") fchdr.atanufacturar, I. l.aptr); 
If (ndx.nanufacturar |a 10) 
( 
printfCBMOR: Sot a PCX fila.\n-)j 



Volume 2, Numbed 3 



cleanup i ) ; 
) 

/"•• Next byte la ZSoft PC Paintbrush version. 

frttdl(ch»i •) fchdr.verelon.l.l.eptr); 

/••• How convert to string. ■••/ 

switch (hdr. version) 

< 

caee 0: 

t • -3. 5"; 

brack i 

C«M 2 I 

t - -2.8 with pallette lofo-( 

break/ 

CSS* Si 

t • "2.8 without pallette lnfo-j 

breeki 

case 5 1 

t . -J.O-i 

break* 

dafaulti 

t - -UNKNOWN- ; 

break; 

i 

/••• Next byte la encoding "ethod •"/ 
freaddchar •) fchdr. encoding. 1. l.eptr) i 

/••• Next byte la bits per.pixel •••/ 
freaddchar •) fcbdr. bits per pixel. 1, J, spin ; 

/■•• Next 2 bytee are xnln •••/ 

readlnt ( J j 

hdr.xsvln - flnaltessp; 

/••• Next 2 bytes are yaln •■-/ 

readlnt ( ) ; 

hdr.ymln • flnaltessp; 

/"• Next 2 bytes are naax •••/ 

readlnt! ) i 

ndr.xnax ■ tlnaltesapj 



prlntheaderO 
Prints header Information to eg 



/••• Next 2 bytes are ymex 

readlnt ( ) ; 

bdr.ymax ■ flneltesE?: 



7 



void prlntheederO 
1 

'*" Print header Information to CLI screen •••/ 

print f (-\nlnformat loo f rest \*i \n\n". eource) , 

prlntfCCreated with PC Paintbrush version 
\e.\n-.t)j 

prlntf {-Coapresslon method: -), 

If (bdr. encoding i- 1) 

( 

prlntf ("None.\n")i 

) 

else 

( 

prlntf ('Run Length Encoding . \n- i ; 

> 

prlntf ("Number of bite per pixel - \u.\n-, 

hdr.blts per_plxelli 

prlntf (-Beglna at (\u. \ui and ends at (\u. 



/""■ Next 2 bytes are hxes ••■/ 

readlnt ( ) j 

hdr.hres - flnalteop* 



Vil . \n" 

hdr. xmln. hdr.ymln. hdr. xmex. hdr. ymax)i 
prlntf 

("Created on a device with \u x \u dpi 
resolution. \n". 

bdr . hres , hdr . vraa ) .• 

prlntf <-Image contains \u planes of data.\n". 
hdr. color planes); 

print ((-Uncompressed line has \u bytea of date.Nn", 
hdr. bytes per line) ; 
prlntf (-Image palette la -); 
if (bdr. palette type - 1) 
( 

print f ( -color . \n- ) i 
1 

else if (hdr. palette type ■ 2) 
( 

prlntf (-gray. /n-) f 
) 

alee 
< 

prlntf (-unknown. \n">; 
) 

prlntf ("Unccaspreesed file alia - \u.\n\n\n-. 
((unsigned longJhdr.ymex - (unsigned long) hdr. ymln 
* 1) 

• (unsigned loog)hdr. bytea per. line • 
(unsigned longthdr .color planes > ; 



/"*• Next 2 bytes are vree ■••/ 

readlnt ()i 

bdr.vres ■ flnaltessp; 

/••• Next 48 bytes are palette -••/ 
freaddchar ■) fchdr. palette. 48. 1. eptr) i 

/"' Next byte la vmode (reserved) "•/ 
fseek(aptr, 1.1) i 



/"■" Next byte la color planes •••/ 
freaddchar *>thdr. color planes. 1. 1, aptr) , 

/••• Next 2 bytes are bytea per line •••/ 

readlnt ( ) ; 

hdr.bytas_per line - flnalteegp; 

/•■• Next 2 bytes are palette type •"•/ 

readlnt (Jj 

hdr.palette_type - final temp; 

/••• Next 58 bytee Is filler*'-/ 
freaddchar •) thdr.f illar. 58. 1. aptr) ; 



readlnt ( > 
Intel procaaaors store short lntegeta -backwards.- The least 
significant byte cones first, followed by the moat signifi- 
cant byte. We have to read the* and put them In the right 
order, 

void readlnt () 
< 

freaddchar -I fck. 1. 1. sptr) i fees *.,,, fl „ t 

byte ■•■/ 

xtemp ■ (unsigned lnt) k; 

freaddchar •) 4k. 1. 1, aptr I i /••> Read next 

byte •••/ 

otessp - (unaigned lnt) kj 

gtemp <<- 8; /••■ Shift 2nd byte left by 8 bite 



Una lt« 






(xti 



gtesspd 



/' 



OB 



getactlonO. gctmeasageO, geteventt) 
Theae functions check for and act on user Input. 



void getactionu 



10 
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void openl lb* ( ) 



void 
t 



while liju it •- 0) 

( 
gatmongK ) ; 

getevent ( ) i 



(•tMMigill 



cl**l 

cod* 



0; 



walt(l << a*lnwlndow->U*erPort->*a? SlgBlt); 

whll*(**ag ■ aetKeg(mainwlndow->UeerPort ) I 

lftawag I- HULL) 

f 

claaa - Bjeag->Cla*e; 

coda ■ m**g->Codai 

ReplyH*g<*»eag) ; 

J 



Intuit lonBeae - (atruet Intu 1 1 lorJtaa* *1 
Open Library ( "Intuit Ion . 1 lbrary" . i • 
lfUntultioofi*** — NULL) 

I 

cleanup i ) i 

1 

GfxBaao ■ (atruet Gf xBase *) 
openL ibr a ry< "graphic*, library. 0) .- 

lffOfxBaae -■ MOLL) 

< 

Clauupll; 

) 

Layer*Ba*e - latruct Layers Base •) 

OpenLlbreryl "layers. library", 0) j 

if (LayereBase — NOLL) 

( 

cleanup O J 

1 



void 
1 



get event ( ) 

if (class -- KENUPICK) 

t 

lflcode -- MXNUHOLL) 



pic* ■""/ 



return j 

If (KKNUNUMlcoda) « 0) 
/ 
( 

if (ITKMNUM(code) — 0) 
( 

quit - 1; 
latum; 

) 
I 
I 



/••• It'* not a 

IC'a the Project 

/••• Quit ••"/ 



If the aouae pointer 1* near the edge of the 
acr**n, aaaua* that u**r want* CO acroll Id that direction. 



op*nb*i() 
Create* bitmap to be uaed by SuperBltHap window. Allocate* 
■enory for each plana according to Information found In th* 

PCX header. 



vhll*(malnacre*n->Moua*y « 30) 

( 

Micro LI ■ 0; 

yacroll - -5j 

doacrollOi 

> 

whil*(maln*creen->Moueer > 380) 

I 

xscroll ■ Oj 

yacroll - 5| 

doacroll ( ) i 

t 

while (Minscrean->Mou*eX < 30) 

( 

yacroll - Oj 

xacroll - -'-.; 

doacroll ( ) ; 

1 

whllet«ainBcreao->MouseX > 620) 

( 





yacroll ■ Oj 




xacroll ■ S; 




doacroll ( 1 : 




) 


> 





openllba< ) 

Open* libraries required by ShowPCX. 



/ 



vo id openba ( I 



■ybitmap - m11oc(*1z*o( litruct BltKap))) 

ifffaybitswp 1- 0) 

{ 

Inl t Bit Map (Biybl t map. hdr .color planea, wlndowwidth, 
windowhelght ) ; 

forll ■ Oj 1 < hdr.eolor_planaii !••) 

I 

If {(nr/bltnap->Plan**[ll ■ 

( PLAHKPTB) Al locRaater (wlndowwldth, windowhelght ) ) 

-- NULL) 

1 

printffNot enough maaory for bltatapI'lJ 

cleanup) ) i 
> 

BltCl*ar(BybltM*p->Plan**(l). 
RASSIZI(wlndowwldth.wlndowbalghe).O)) 
> 
I 

alaa 
< 

printf (-Can't allocate nswaory for bita*pl-|j 
cleanup!) ; 
) 



openwlnl) 
Open* screen, window. BaatPort. Viewport and 



iu atrip. 



void 
( 


openwln ( ) 




NewSc reen . L* f t Edge 


■ Oi 




KewScreen . TopEdge 


■ Of 




HewScreen.Midta - 


acreenwidth; 




KewScreen. Height ■ 


scraanheightj 




NewScreen. Depth ■ 


acraendapthi 



NewScreen. Detail Pen - Of 
NewScreen. BlocxPon ■ li 
N*w3cr**n.VlewHod*a • HBLLi 
If (acraanwidth <- 330) 
Ne-Screen. VlewKodss - NULLi 
If [acreenwidth > 320) 
NewScreen. VlawModa* I- HIRES; 
if (acreenhelght > 200) 
NewScr**n.viewMode* I- LACIj 
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1 1 



NevScreen.Type . CUSTOKSCHJMMj 
NevScreen.font - MUU,; 
NewScreeo.DefeultTltle . HDLLi 
HevScreen. Gadget* . wjlLj 
MavScr**n.Cu*tom8itHap - KULLi 

If ( (wlnictiOT ■ (atruct Screen 
•IOp*oScte»n(4Ht«ScrMn) ( 

■ ■ NOLI.) 

< 

prlntf(-Vn»ot enough if— o.y to op,,, BCC#M , Vn -, 

cieenupn j 

I 
ShovTitle(*«ainacreen.PAl£i:i ; 

NevWlndow.LeftKdge - 0; 
Wev*lwlow.TopIdg« . 0i 
Nevwindow. Width . windowldth; 
HewWindow. Height . wlridowheight/ 
HewWindo»..DatailPen ■ 0; 
NewVlndow.BlockPen ■ 1; 
MewWlndov. Title ■ HULL; 

NewWlndow.Mage . supra BITXAPIBORDKRL1S5IACTIVATE 
■.EPORTHOUSEj 
KevWindow.IDCXPI'lega . 
HEMUPICK I ACTIVTWINDOWI MOOSDWVtj 

NavWindow.Type . C08TOH9CREEH; 
Kewwindo-.riretQedget - MOLL/ 
NevWindov.CheckKork - MOLL; 
NewWindow. Screen - Mlnacreen; 
NewWlridow.BltKap - Bybitaap; 
HevWindow.llinWidth ■ 30; 
KewWlndow.MlnHeighc . 30. 



KewK 1 ndow . HaxWl dth 
NewWindow.KaxHelght 



vlndowidthi 
vindowhelghtj 



1(( (Htnwlndow - (etruct Mlndov 
•)OpenWlDdow(tNewWlndow) I 



iry to open wlndowl \n-) . 



print f |-\n»ot enough 

cleenupO j 

> 

rport ■ nelnwindov->RPort; 

vport - fc»airr«iodow->WScreen->VlewPort; 

SetMenuStrip(e t einwlndow.4quit«enu), 



cleanup* ) 

Cloeee anything end everything we have opened. 

void cleanup) ) 
I 

if Captr) 

fcloaa(eptr) ; 

ford - 0, 1 < hdr. color plan*.; i..| 

1 f <«ybit»*p- > Plane* (i J ) 

FreeRaeter(Byblt»ap->Pl«neeIl],windowvldth. 
wlndovhelght)i 

) 



If (oybltaap) 

< 

freeinybltnap) j 

■•tMa(aybltHp,ii I(0 f <nybit»ap) .01.) j 

1 



r REXX PLUS CflMPHIB ■= 

Order the only REXX Compiler designed for the 
Amiga, so YOU can: 

O Create- REXX code that executes from 2 to 

15 times faster 
O Use - more built-in functions 
O Find - most syntax errors with a single compile 
O Make - often used REXX programs resident 

All this and more for $150. 




DineeM 
Ebivards 




19785 West Twelve Mile Rd. Sulie 305 

SoulhlieW. Michigan 48076-2553 

To order call (313) 352-4288 or write to the above address 

Shipping ft handling: Foreign orders $15; US and Canada bated on 

■nipping /one Payment muil be made in U S fund* drawn on U S bank 



CleaiHenuStript»aln«lndow) , 

If iMlnwlndow) 
CloaeWindovlBMinwindow) ; 

if (■ainacreen) 

CloaeScreen(mainecreen) , 

If (LayeraBeaet 
CloaeLibrary(LayereBaae) ; 

If (OfxBaee) 
CloeeLlbrary(OfxSeee) j 

If ( Intuit ion&aee) 
CloeeLlbrarydntultlonBeaejf 

exit(0J/ 







Please Write to: 

Gary L. Fait 

c/o AC'S TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 



Circle 



106 on Reader Service card 



1? 



AC'S TECH 



Two of life's essentials 
AC TECH Amiga 



AC'S TECH For The Commodore Amiga is the first disk-based 
technical magazine for the Amiga, and it remains the best. 
Each issue explores the Amiga in an in-depth manner un- 
available anywhere else. From hardware articles to pro- 
gramming techniques, AC'S TECH'is a fundamental resource 
for every Amiga user who wants to understand the Amiga 
and improve its performance. AC'S TECH offers its readers an 
expanding reference of Amiga technical knowledge. If you 
are constantly challenged by the possibilities of the world's 
most adaptable computer, read the publication that delivers 
the best in technical insight, AC'S TECH For The Commodore 
Amiga. 




AC GUIDE Amiga 




AC'S GUIDE is a complete collection of products and ser- 
vices available for your Amiga. No Amiga owner should be 
without AC'sGUIDE. More valuable than the telephone book, 
AC'S GUIDE has complete listings of products, services, 
vendor information, user's groups and public domain pro- 
grams. Don't go another day without AC'S GUIDB 



AMU 







100% of the recommended daily 
allowance of Amiga information. 

1 -800-345-3360 



HiSoft 's HighSpeed Pascal 



by David Czaya 



Highspeed Pascal (vl.OO) from HiSoft, is .in aptly named 
Pascal IDE (Integrate! IXvelopment Pnvironment) for (he 
Amiga which closely adheres to the programming charai tens- 
tics of TurboPascal by Borland Inc. 

The HSPascai environment consist*, of a text editor which 
gives complete control over editing, compiling, debugging, 
and running your programs. For people who wish to use their 
own editor or run things from the CI. I. the compiler and 
debugger are runnable as standalone programs. 

Installation, though not automated, can be accomplished 
by moving a few directories and program files, I his is all very 
well documented in the manual, and icons are provided for 
Workbench use. 

TurboPascal Compatibility 

I lighSpeed Pascal has a high degree of TurboPascal v5.0 
compatibility. This includes support for dynamic length 
strings. DOS, CRT. and Graph units, standard function names 
and parameter lists, .is well as other TurboPascal extensions to 
the Pascal language. 

The compatibility does not include any of the TurboVhhn 
COP (Object Oriented Programming) or Windows concepts 
available in TurboPascal v5.5 and abo\ ,■ 




nonth 



»rot«r* 

fbvgln 



*rr*v 



3t 






»t*T in*; 

; arrav I* 

l'«r«nCount *> 



i 

roi 



.61 of chap; 

thtn er<jin 

- •nltr « v-l it) d 



i-mttarv path' ): 



t u ;ttP«r«nStr<l>,nnvr M*.»J; 
rt*nt ( % > ; 

» (po»Irror • • > do boaln 

uriMi.Nwt): 

GoioJcrtSi .vJ; 

• l«* 

uril»(».Sli»:a.- '); 



'OF" (.lit 



PPOt»* til 

s.llttr in« 

4111 

JIM 

* . Rt lr am 

• ■"Mr mm 
f .Rttr 

Hiii 



iffli 



fep lftti?r B 



am 



Ew*rut*FIa 
:r *nd D*]*t*f i*a 
r tot :■ i to 6 do 

uriuioroltcllcnl ]>; 



criptrlag>B ini>r ppot*cl 
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I have compiled many complex TurboPascal programs 
without a single change. The most predominant incompatibil- 
ity occurs when the source code uses hardware specific 
programming (mouse, inline code, assembler, etc.). Also, it's 
noted that data files written for TurboPascal may need the byte 
order swapped before using with HSPascai because of the 
manner in which the 680x0 and the 80x86 machines store data. 

Typically, when the programmer uses the TP units for 
text, graphics, and IX>S, the source code will compile and run 
just fine. This, in itself, is immensely exciting considering the 
abundance of TurboPascal source code available online, on 
disk, and in reference books. 

Programming with Highspeed Pascal 

There are many books teaching and referencing 
TurboPascal and any one of them can be used with Highspeed 
Pascal HSPascai uses the "unit" concept which made 
TurboPascal stand out above the rest. A unit is similar to a 
module in Modula 2 or a library in C. H allows you to create 
Functions and procedures which may be included in other 
programs rather than rewriting the Code within each program 

I ISPascal (as well as TurboPascal) include powerful 
functions to simplify certain programming tasks. The DOS unit 

supplies functions for file I/O, 
directory! and command line 
handling, and date-time 
manipulation. 

The CRT unit provides 
console window procedures 
including keyboard I/O, text 
styles, cursor placement, etc. 

Finally, the Graph unit 
provides I'urboPascal compat- 
ible routines for screen 
resolution, color palette, font 
styles, text justification, 
graphic til) patterns, aspect 
ratios, 2-D and 3-D bar graph 
drawing, pixel, line, poly, and 
image drawing. 

HSPascai is ver) similar to 
ISO and ANSI Pascal although 
there are some rather insignifi- 
cant differences and exten- 
sions to the language 
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i isi'.isi.il can access .mv Amiga 
library, device, or resource. An included 
utility converts standard Amiga function 
definition (id) files to HSPascal units. Each 
Amiga system function has been converted 
in this manner (v2.04 units will be avail- 
able by the time you read this). In addition. 
all types, and constants from the Amiga C 
language "include" files have been added 
giving complete access to the Amiga 
Sj stem. I he function names, calling 
conventions, and constants all use the C 
names and syntax wherever possible. 

HSPascal includes an inline assembler 
supporting the full 68000 instruction set— 
with minor compiler restrictions. This 
allows you to write regular assembler 
statements using assembler operators and 
directives mixed with standard Pascal 
labels, constants, and variables. This is a 
very powerful concept for easily adding 

assembl) language routines to vour code. 

A programming problem you will 
encounter has to do with Pascal text 
strings. Pascal uses a length byte followed 
by (he string's characters (essentially the 
same as BCPL strings) HiSoft has added 
two functions, PasToC and CToPas, to 
cope with conversions to C style, null- 
terminated strings which vou will need 
when working with the Amiga. 

Another potential problem inherent to 
Pascal is that of allocating memory off the 
heap with New or Get Mem. There are no 
provisions to specify memory type on the 
Amiga (i.e.. Chip. Fast, etc.). 



The IDE Editor 

Highspeed Pascal includes separate 
editors for Amiga DOS 1 .3 and 2.0 users. 
They appear and function identically so 
that vou simply choose whichever applies 
when Installing HSPascal. 

The editor has an intuitive design that 
conforms closelv to Release 2-stvle 
guidelines. It runs fast and has good 
mouse, keyboard, and menu control. The editor fully 
supports the clipboard copy-cut-and-paste, an extensive 
print facility, undo and undelete line, fast find and replace, 
bookmarks, and more. There is even a recorder-stvie macro 
player to perform repetitive editing tasks. 

All environmental settings can be made from the editor 
with gadgets, path requesters, check, radio, and cycle 
gadgets. You can compile, set program arguments, debug, 
and run your programs from simple menu commands or 
logical keyboard equivalents Nearly everything can be 
controlled from the keyboard or the mouse even within 
special requesters. 
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Strangely absent are some of the more basic editor 
function> such as case conversion and character swap. Also, 
there is no AKew interface provided. 

C. ompilation errors are flagged first in a popup requester, 
and then in the editor's title bar. The cursor is placed on the 
first error ready for correction. 

The Compiler 

HSPC, die compiler/is a single-pass compiler/linker. It 
includes standard options for range .n^ stack checking and 
inserting debug symbols as well as I/O and var-slring error 
checking. The compiler manages your projects with a built-in 
'make" function. Vou can make only modified units or build 
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extensive libraries ol precompiled units and 
not worry aboul Unking everything in. result- 
ing m bloated executable*. 

Full support for single and double IEEE and 
an extended 10-byte internal math formal is 
provided 

I UghSpeed Pascal is fast l USoffs literature 
claims a "compilation speed of more than 
20,000 lines per minute" and I have found no 
reason lo doubt their claim. 

The Debugger 

I liSoft includes the MonAm debugger which 
is from the Devpac sssembler. By selecting 
"Debug" from the IDE menu or running 
MonAm from thet II. ,i screen with several 

windows, calleda Pronl Panel, will appear I he 
windows display the current state ot the 
registers, memory, source code, and disas- 
sembled program instructions with symbols, 
Your program will be suspended at the first 
instruction with a breakpoint 



Highspeed Pascal is fast. 
HiSofts literature claims a 

"compilation speed of 

more than 20,000 lines per 

minute" and I have found 

no reason to doubt their 

claim. 



-*a 



all units from scratch. Limited conditional compilation is 
supported. DEFINE and UNDEF provide a means to 
control range checking, hardware implementations, etc. 

Startup and exit code is internal lo the compiler, being 
a pari of the System unit. I find this a poor choice as it 
make-, it impossible to modify the startup. Access to the evil 
code is provided so you can implement termination 
procedures. 

Standard Amiga executable*, are produced directly bv 
the compiler. There are no provisions for specifying 
whether data is to be loaded into CHIP memory (lor image 
data) Amiga object files written with Dcvpak or SAS ( 
can be linked in and their procedures used with your Pascal 
code. 

HSI'C uses "smart linking" to exclude unused proce- 
dures trom your program. This allows you lo create 



You can examine the Information m the 
various windows or issue a command to 
MonAm. Commands include running, tracing, 
or single stepping the PC (executing instruc- 
tions), setting breakpoints, adjusting the 
display windows, or quitting. All commands are keyboard 
issued. 

There are live different types o! breakpoints available 
including counter and conditional breakpoints. You can set 
breakpoints by address, expression, or source line number 
address. There is a help screen which displays pertinent 
Information and lists the breakpoints set. and a historv butler 
which displays up to hve ot the most recent breakpoints and 
exceptions which occurred. 

II would take several more pages to lisl all the commands 

and features available on MonAm. It suffices to say thai It is.i 
well-built ,md very powerful debugging tool. It is also, in my 

opinion, a drawback to the entire pat kage. Now, understand 
that MonAm is a very powerful debugger, but il Is also verj 
complex and intimidating— so much so, that I have barely 

used il 
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The rest o! the f lighSpoed package is geared towards the 
casual or professional programmer who desires the simplicity 
of an IDE with a powerful vet clean and understandable 
version of Pascal. Yet this debugger is for programmers with 
extensive knowledge of assembler and low-level debugging 
skills, 

To be fair, I have used the debugger successfully without 
much hair-pulling, but it is certainly not what I would call 
"user friendly." Highspeed Pascal virtually begs for a good 
Source te\ el debugger along the lines ol the Benchmark or Manx 
SLD. 

The Manuals 

Highspeed Pascal comes with two lay-flat, spiral-bound 
manuals. The first is a 200-page User Manual which includes 
Installation, a quickie tutorial, separate chapters on the editor, 
compiler, and debugger, usage of included utilities, and a 
description of all the Amiga Units that are included for Amiga 
<-ystem access. 

The second manual is the Technical Reference manual 
which describes the Pascal implementation and the other units 
supplied, including the System, CRT, DOS, and Graph 
TurboPascal units. 

Each procedure and Function is detailed with the calling 
declaration, a (unction description, comments about the 
procedure, references to other or similar functions, and a 
standalone example program which uses the procedure. 

Both manuals have a Table of Contents as well as moder- 
ately useful indexes. I would have liked a reference card of all 
the many functions. There are just loo many to remember, and 
paging through the 280* page reterence manual is taxing 

The manuals are not Pascal language tutorials. They are 
references to the Highspeed Pascal implementation and 
nothing more. If you do not know Pascal, buy a TurboPascal 
tutorial book and you will be ready to go. 

Conclusions 

I have been programming in Modula 2 for many years, but 
have never tried Pascal. I picked up the language very quickly 
just by examining public domain TurboPascal source code. The 
languages are all very similar and the units concept was very 
familiar to me. 

I am much impressed with the speed and operation of 
HSPascal. The IDE makes working with HSPascal quick and 
pleasurable. I long for a better source level debugger, though. 

The TurboPascal compatibility is what really makes this 
package shine. I have a lot of TurboPascal source code which I 
acquired from various public domain libraries and much of it 
compiles and runs without change. If you are about to start 
porting that special TP program into C so it can be used on the 
Amiga, this package will pay for itself in moments. 

I have not encountered any compiler bugs. I did note a 
minor problem in a System procedure, which HiSoft said 
would be corrected in the next upgrade. There may be other 
problems, but after several weeks of heavy use, I haven't found 
them yet. 

The editors method of highlighting text is somewhat 
awkward, but certainly not buggy. The manuals are informa- 
tive h ith many examples and few typographical errors. 

Several levels of product and technical support are 
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ne BASIC package has stood the test of time. 

Three major upgrades in three new releases since 1988 . 
Compatibility with all Amiga hardware (500. 1000. 
2000. 2500 and 3000). Free technical support... 
Compiled objed code with incredible execution 
times Features from all modern langu* 
and an AREXX port This is the 
FAST one you've read 
much about! 




F-BASIC 4.0 System 

Includes Compilef. Linker. Integrated 

Editor Environment User's Manual & Sample Programs Disk 

F-BASIC 4.0 + SLDB System $159.95 

As above with Complete Source Level DeBugge' 
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available from HiSoft; however, as the companv is based in the 
U.K., the support programs are not very economical for U.S. 
owners. HiSoft representatives otter online support with 
regular appearances on both GEnie and Bix. They have been 
very prompt and helpful with my many questions. This is the 
alternative language I've been waiting for. Highspeed Pascal is 
lor the rest ot us. C you later... 

TurboPascal is a registered trademark of Borland Inc. Arnica is 
a registered trademark of Commodore-Amiga Inc. Highspeed 
Pascal and MonAm arc registered trademarks of HiSoft. GEnie 
is a registered trademark of General Electric. Bix is a registered 
trademark of General Videotex Corp. 







Please write to: 

David Czaya 

c/o ACs TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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Understanding th 
Console Device 



by David A. Blnckwell 



Introduction 

Some time ago I attended .1 computer programming 
course at a local funior college The computers we used for the 
course were IBM compatibles. Being mostly familiar with the 
Amiga. I thought this would be an exciting learning experi- 
ence. 1 was somewhat disappointed when I found out that the 
IBM machines were not nearly as challenging to program as 
the Amiga. Some people may enjoy the ease of such an 
uncomplicated operating system On the other hand, I enjoy 
the challenge of programming an Operating system as power- 
ful and sophisticated as the one in the Amiga. 

I began to try to duplicate the programs we were writing 
in my college course on my Amiga. Some of the aspects of 
these programs included manipulating the cursor on the 
screen and performing single character input. The standard C 
routines provided in my compiler did not have the capability I 
was looking for. There were no functions at all to handle the 
cursor. The character input routines required me to press the 
return key before my program would receive the character. I 
wanted to be able to read the key as it was pressed. I decided 
my only option was to search through the Amiga ROM Kcmal 
Reference Manuals to see what 1 could find 

Console Device 

The console device seemed to be what I needed to make 
my program work the way I wanted. The information in the 
reference manual, although complete, did not clearly convey to 
me exactly what I wanted to know. I still had nagging ques- 
tions about certain points I wasn't sure about, so I did what I 
always do under those circumstances: I wrote a program to 
experiment with the console device and gain firsthand 
experience with it. It is that experience thai I hope to pass on to 
you in this article and give you a basic understanding of the 
console device thai will allow you to quickly put the console 
device to use. I suggest you read this article in conjunction 
With the Amiga ROM Kertuil Reference Manuals. If vou do not 
own these reference manuals, 1 highly recommend them. 

Standard Device Commands 

The system programmers for the Amiga operating system 
chose eight standard device commands for all devices de- 
signed to operate on the Amiga. Devices do not exactly have to 
support every command as long as they respond to each 
command. Normally an error code is returned for the com- 
mands a device docs not support. 



Console Device Commands 

Of the eight standard device commands, the console 
device only supports three. They are the CMD Q l : AR, 
CMD_READ and CMD.WRITH commands The fact that only 
three standard commands are supported does not detract at all 
from the console device, and actually makes it quite easy to 

use. ThcCMD_CLEAR command instructs the console device 
to clear its display The CMD_READ command causes the 
console device to read an indicated number of character- from 
the input stream and return them to you. Finally, the 
CMD_WRiTE command makes the console device write the 
provided string to its display. The console device has addi- 
tional non-standard commands but they are beyond the scope 
of this article. After you have decided that you want to us,- the 
console device, you must perform the following steps to set it 
Up for Use with your intuition window. 

Getting Started 

The console device, with only one exception, must be 
attached to an already opened window. (The one exception to 
this requirement is beyond the scope of this article Maybe I 
will be able to cover it in a future article (Once you have the 
window open you are ready to continue. 

The next step is to allocate an I/O request structure to use 
with the console device. This is extremely easy to do and can 
be accomplished with the following code: 

struct IOStdReq 'myMessage; 

my Message s CreateStdlOlinyPort ) ; 

If you are going to use synchronous I/O, you will want to 
allocate two structures for use. You will use one for your read 
requests and the other for your write commands. If vou want 
to use asynchronous I/O you can get by with one global 
structure and clone all your read and write requests from it as 
you allocate them. This is the method 1 use in my demonstra- 
tion program. I feel it is the most flexible since it allows vou to 
accept input trom more than a single source. In mv demonstra- 
tion program you will notice that I use both the console de\ ice 
and an IDCMI' (Intuition's Direct Communication Message 
Port) for input 

Once you have an I/O request structure allocated, place 
the pointer to your window in its 10 Data field and the length 
of the window structure in its io_Length field. Then you call 
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Standard Device Commands 
Console Input 
Console Output 
Getting Started 



the OpenDeviceO command. The following code demonstrates 
these points 



•-h. cental < 



rnyMessage->io_Dat. 

nvMessage->:o_Le:. :• .. slzeof (SI nict Window) ; 
OpenDevicet "console, device", 0, m/Message, 0); 

ThfOpenlX'viccO function fills in the io_ Device and io_Unit 
fields of your I/O requesl Structure. In synchronous communi- 
cations, the io Device and io_Unit fields are the ones you will 
duplicate in your second I/O requesl structure. In asynchro- 
nous communications, you clone the same two fields in each 1/ 
O request structure you send to the console device. Once all 
this is done, you are ready to start communicating with the 
console device. 

Console I/O 

If you are using synchronous communications, most of 
your work is already done. To write to the console device, you 
need only place a pointer to the string you want written and its 
length in the io_Data and io.Lcngth fields of your I/O request 
structure I o read from the console device, you put a pointer to 
.i data hufferand its length in the io.Data and io.Length fa-Ids 
of your I/O request structure. The io_Length field not only 
specifics the length of vour data butter but also tells the 
console device the maximum number of characters to return. 
Asynchronous communications on the other hand are a bit 
more involved. 

To perform asynchronous communications, you will need 
to allocate a new I/O request structure each time you wish to 
communicate with the console device. You clone the required 
fields from your global I/O request structure into the new I/O 
request structure you just allocated Next, place the console 
command in your structure's io_Command field. Now allocate 
the data buffer memory area and place its pointer and length 
into the iOjData and io_ Length fields It \ our data area has 
already been allocated, all you need to do is put the proper 
values in the correct structure fields. That is the method I use 
in my demonstration program. An example of functions to 
handle asynchronous read and write commands follow: 

■ ■ ■ 



■BO-.. 

_Cao»«rKl . CMDJlEAD; 

■ 






length) 
dfloq *m»g; 

■ i ih* con 



■ 






(WQ 



C :■:.!( 






goto cv 



Ml •/ 

■ 
nig->io.ConMnd - CKD_MKITE: 
UTRiatringt 
n«g->>o_L*ngtb ■ l«ngi 






You will notice that I used theSendIO<) function in my 
asynchronous communication functions. If you are using 
synchronous communications, you will want to use the DolOO 
function since it waits for the device to finish its processing 
before it returns control back to your program That is how 
you send messages hack and forth between your program and 
the console device. Now let's look and what you can send or 
receive. 

Console Output 

Besides the usual character strings you can send to the 
console dei ice, there are numerous control sequences, both 
ANSI standard and Amiga non-ANSI standard, which you can 
send to the console device to manipulate it in various ways 
Lists One and Two contain a complete list of these control 
sequences. 
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WhiTi- i! is indicated that you need to enter .1 value, you 
always use ASCII characters to represent the digits ot the 
numeric value. For example, to represent the numeric value 20 
in ASCII characters, you would use the hexadecimal numbers 
32 and 30. The reason you use hexadecimal numbers rather 
than decimal is that the hexadecimal number 30 represents 
zero. Therefore, all you need to do to get the digit you want is 
to add its value to the hexadecimal number 30. I'd get the 
number five just add 5 to 30 to get the hexadecimal number 35. 
I'm sun- you Will agree that the hexadecimal number 30 to 
represent zero is easier to read and understand than the 
decimal number ■ 

Concerning Usl I wo. you cm enter more than one event 
type into the SET RAW EVENTS and RESET RAW EVEN 1 S 
control sequences as long as they .1 separated by semicolons 
(hex value 3B). List Three contains a listing ol .ill the event 
types used m these control sequences I hese event types 
determine what type of input you receive from the console 
■ 



List One: 






ANSI Standard Control Sequences 




BACKSPACE 


08 




1 l\l FEED 


0A 




VERTICAL TAB 


0B 




FORM FEED 


OC 




CARRIAGE RETURN 


OD 




SHIFT IN 


0E 




SHIFT OUT 


OF 




ESC 


IB 




CSI (Control Sequence Introducer) 


9B 




RESET TO INITIAL STATE 


IB 63 




INSERT IN] CHARACTERS 


9B|N)40 




CURSOR UP [N| LINES 


9B[NM1 




CURSOR DOWN |NJ LINES 


9B [N] 42 




CURSOR FORWARD [N] SPACES 


9B|N]43 




CURSOR BACKWARD [\| SPACES 


9B[N|44 




CURSOR NEXT LINE |N] (to column 1) 


9B|N]45 




CURSOR PRECEDING LINE [N] (col. 1) 


9B[Nj4c 




MOVE CURSOR TO ROW; COLUMN 


9B [R] [3B CI 48 




ERASE TO END OF DISPLAY 


9B4A 




ERASE TO END OF LINE 


9B4B 




INSERT LINE 


9B4C 




DELETE LINE 


9B4D 




DELETE CHARACTER | N | 


9B|N]50 




SCROLL UP |\] LINES 


9B [N] 53 




SCROLL 130WN [N| LINES 


9B IN] 54 




SET LINEFEED MODE (RETURN-LINEFEED) 


9B 32 30 68 




SET LINEFEED MODE (LINEFEED ONLY) 


9B 32 30 6C 




DEVICE STATUS REPORT 


9B36 6E 




\^ 







Console Input 

If you have not selected RAW input ev cuts, then vou will 
receive the AS< ll-equiv alent character tor the ANSI standard 

kej s on the kej board For the other keys, you will receive an 
escape sequence of two to four characters. List Four contains 
the escape sequences for the non-ANSI standard keys. This 
form of input, sometimes called COOKED KEY EVENTS, is the 
default. I his is the easiest to receive and process. The one 
disadvantage >* 'hat you do not receive any other information 
ow the key press other than shifted or unshifted. You don't 
know if the Alt. \MK..\ot( \r\ keys were used. 

II you need more information about the keyboard inpuf 
events, sou send the SET RAW EVENTS control sequence to 
the console device. You can request any combination of input 
events trom List Three. If later you want to reduce the number 
of input events you want to receive, you issue the RKSET RAW 
I VI \ IS control sequence with the appropriate event 
number(s) thai you no longer want. With these two control 
sequences vou can precisely control the Information you 

receive from the console device The format of the returned 

information is very different from the 

cooked format and requires more process- 
ing to use fully. 

Instead of receiving a standard 
WSI-siandard character code vou receive 
what is known as a "complex input event 
report." This report takes the form of: 






The exact format of this report is what was 
the biggest problem for me as I n .is 
studying the Amiga ROM Kental Manual. In 
experimenting with the console device, 1 
discovered thai this is returned as a null- 
terminated ASCII string 1*0 use the values 
in the report, you must convert the 
different parts of the string you want to 
use to the correct numeric formal I he first 
iiv e fields of the complex input event 
report as broken out as follows: 

'nation 
I 



The remainder of the fields in the complex 
input event report are self-explanatory. It 

is important to remember that the keycode 

is not the ASl II code but instead, it is the 
number of the key in the keyboard matrix. 
To convert it to the ASCII character code, 
you call the KawKeyConvcrtO function. 
This function requires a global variable by 
the name of "ConsolelX-vice" be assigned 
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ihe pointer to the console de\ ice 
structure. You can do this .titer you 
call tlio OpenDtt keO Function as 
demonstrated in the following code 

myHes- 

■ 
>lo_Df 

Then before you call Ihe 
RawKevConverK) function, you 
allocate an input event structure and 
fill in the ie_Codeand ie.Qualifiet 
fields with Ihe keycode and qualifier 
values returned in the complex input 
event report. However, you can't use 
the values tl s they are returned in the 
report. You need to convert them to a 
numeric value. There are two func- 
tions in my demonstration program 
that provide one method to do this. 
After the input event structure is tilled 
in, then call the RawKeyConvert() 
function. One of the arguments you 
supply to this function i> a buffer for 
the converted character When this 
function call returns, this is where vim 
will Find vour converted character The difference between 
using mis method to gel your ASCII character code and just 
asking for cooked keys in the first place is the reporting of 
qualifiers in the complex input event report 

The qualifiers returned are quite explicit Not only doe> it 
report if Ihe SHIFT. Alt or AMIGA keys are beinj; held dow n. 
but it also distinguishes between Ihe left and ri^hi keys. There 
are many other qualifiers that you can receive also. The 
qualifiers you receive are determined by which class of raw 
kej events you requested to receive list live contains a 
complete lis! ot the possible qualifiers Some of these qualifiers 
you probably will never need. I included a function in my 
demonstration program thai converts the qualifier section of 
the complex input event report to a numeric value that can 
easily be tested and I also demonstrate how to test it for several 
of Ihe qualifiers. 

Demonstration Program 

The accompanying demonstration program should help 
you more fully understand how you can use the console device 
for you own needs and how to use both the cooked key and 
raw key return events. I only request raw kev hoard and mouse 
events in my program, but it could he easily modified to 
experiment with any of Ihe raw event types you are interested 
in. I have also shown an easy w a) to make macros that are 
easy lo understand and use in your own program. These 
macros provide an easy way to home the cursor, clear the 
screen, move the cursor to any position on Ihe screen, etc. The 
program runs wilh raw key e\ ents selected as its default. \\ ith 
the gadgets, you can toggle between cooked and raw kej 
events I he program waits for keyboard or mouse input and 
displays the return value from Ihe console deuce to the m reen 



List Two: 

Amiga Console-Control Sequences 



ENABLE SCROLL (default) 

DISABLE SCROLL 

AUTOWRAP ON (default) 

AUTOWRAPOFF 

SET PAGE LENGTH 

SET LINE LENGTH 

SET LEFT OFFSET 

SET TOP OFFSET 

SKI RAW EVENTS 

RESET RAW EVENTS 

SI I CURSOR RENDITION 

Invisible: 
Visible: 

WINDOW STATUS REQUEST 



9B 3E 31 68 

9B 3E 31 6C 

9B 3F 37 68 

9B 3F 37 6C 

9B <length> 74 

9B <width> 75 

9B <offset> 78 

9B <offset> 79 

9B <even1 types> 7B 

9B <event types> 7D 

9B 30 20 70 
9B 20 70 
9B 30 20 71 



List Three: 

RA W Event Types 

No-op 

1 RAW keyboard input 

2 RAW mouse input 

3 Window Activated Event 

4 Pointer position 

5 (unused) 

6 Timer 

7 Gadget pressed 

8 Gadget released 

9 Requester activity 

10 Menu numbers 

1 1 Close gadget 

12 Window resized 

13 Window refreshed 

1 4 Preferences changed 

15 Disk removed 

16 Disk inserted 



Volume 2, Number 3 



21 



For raw key e\ mis, it also shows the com Cited raw key and 
the most bask qualifiers that arc pressed. 

Experiment with this program to get the most out of it you 
can. As always,! can be reached tor questions or comments on 
GEnie using the e-mail address, D.Blackwelll 



C 



Source Code 



j 



List Four: 




non-ANSI Standard Escape Sequences 


Key 


Unshifted 


Shifted 


Fl 


<CSI>0~ 


<CSI>10- 


F2 


<CSI>1- 


<CSI>11~ 


F3 


<CSI>2~ 


<CSI>12~ 


F4 


<CSI>3~ 


<CSI>13~ 


F5 


<CSI>4- 


<CSI>14~ 


F6 


<CSI>5~ 


<CSI>15- 


F7 


<CSI>6~ 


<CSI>16~ 


F8 


<CSI>7~ 


<CSI>17~ 


F9 


<CSI>8- 


<CSI>18~ 


F10 


<CSI>9~ 


<CSI>19~ 


HELP 


<CSI>?~ 


<CSI>?~ 


Arrow keys 






UP 


<CSI>A 


<CSI>T 


DOWN 


<CSI>B 


<CSI>S 


LEFT 


<CSI>D 


<CSI> A 


RIGHT 


<CSI>C 


<CSI> @ 


(notice the space in last two 


shifted arrow keys sequences) 


(<CSI> isequivilant to9B) 



[e.c 



■ t.h che coi 



Manx Azte<: 

cc ShowConsoIc.c 

In Shc*<Console.o 3. lib 



.u.h> 

ide <exec/typea.h> 
■>xec/io.h> 
■clib'console_protos.h> 

* '■ ,.r.- 



idefine KEHF_CLEAH 

UBYTE EHASEEOLO = { 0x9b. '- 
UBYTE ERASEEOIi 



.. ..... 



Q'. 



rE CNEDCMNII - { 0x9b, '2\ 



• o 



•;• 



■ ■ . ' ' 



1 . ' , 



'H' 1: 

l 



0x9b, 



. 0x20. 0x70 j; 



char • ■ 



List Five: 


'i 


Input Event Qualifiers 


Left Shift 


Numeric pad 


Right Shift 


Repeat 


Caps Lock 


Interrupt 


Ctrl 


Multi-boradcast 


Left Ait 


Left Mouse Button 


Right Alt 


Right Mouse Button 


Left Amiga key 


Middle Mouse Button 


Right Amiga key 


Relative Mouse 



■?q (\n", 

* ■ ■ " i tln_Succl\n", 

Un_Predl\n". 
UBYTE ... :ypo)\n-. 

... 

• . . ... ... 



UWDRD (mn_L« 

Device " ( 



(io_Un,* 



... 
BYTE ... tlo_Error)\n" 

UUW1 i Lo_Actu i 

VUXK lio_LengtM\n- 

APTR 

ULOKJ - • . • 



<CSI>c. 



ersj 






■ 
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■ 

■ 



■ 

h - 






Cons-. -ASKEOl.,2) 

-ASEEOO.2) 

-• 
Con; 
* ( > Console*: . : . • . ■ n : 

■ 

"IRAWKEYINPUT.SI 



■ 



.'. ~ WN.31 



I oit (char •. long); 



Long Cf> nDevi :e(cl 

void 

. ■ • . 

- 
'it ; 

■ - 

- •„-. 
void 

icw *ItoWindowi 

... 

• • 

- ! 
'.MOHD. c: 

■ . • ■ 

•pra<r lO.aOj) 

aldO.aO) I 

..10) i 

- 
■ 

■ ■ 
' KsgPort ■ 
■ 

lOW; 
■ 

boo: 

void n 

I 



low •): 



[Offe ;.;•■:;• 



I 



returnedsignai 



■ 



AXIL done - FM-Sfc; 



goto 



■ 
. : .. 

window.-); 



: (nyPort = CreatcPort CnyConPorf . 01.) 



■ 



B.")| 



' - - I 



■ 
'30 GtlUC- 



iqs 



- ."•• iq 

goto mair._ ■ 



IAPTR) Window; 
"' Window); 

nyMos 



■ 



" 



■nsolc 






•irp_SigBlt i 
gnal 












! 



to request 



UBYTS 

lo»; wdgei 

lowsignal. consolesignal 






• ' .--•.::: t.': . Bufl 

- -0FFI); 

I :done I 

returnedsigi .,- 
-■indowsign.-i; •■<■•■ 

■•■... 

1 :-sage 

" >CetKsg|Window- >UaerPt.r 



I 
gadget_clas 



. 
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ected '.'rryjnessage- 

^age * imyjrcssage) ; 



ttwit< 



•\DGETOP: 

ced->Gaa : 



in _ .-■ , .. ". 1 1 
raw_fceys =_ TP'JE; 
J 

case QUIT: 
done 

■ ■ 
I 

GET_C0OKEDKEYS ( ) ; 
raw_keys = FALSE; 

» 

break; 

defav. 

■ 



■ . ■ 



' . ' : 



; .' ' 

I 

I 

tnedsignals <• . 

while 1 <ry_ioreq 
>GetKsg<iryPort) I ) 
I 

~/_ioreq- ■ . 
I 

...... 

ConsoleReadlbutter. Buf ferLen-1 I ; 

DeleteStdIOtny_ioreq) ; 

I 

i 

I 



SET_CURSORCWO; 

CloseDtrvicefmyMesi. 

mairu- • 

shutdown t I ; 



struc • i- • 

>tessagei ; 



■ 



AD > 



■yPort 

I 

while 



cc IOStdReq 



■' . . : 



:>.;dIO(my_toreq) ; 
) 
DeletePort (myPortl ; 



Window ) 
Clem*.. tow); 



window - open a window and return a pointer to the 
window * met '-if 

Kii • 

struct HewWindow "nw; 
Cruel Window "wind let Window •) 0; 

'Struct NewWindow 
")AllocMem|sizeof (struct NcwWln.; 
goto dw_<'y 





: 


■ 






640; 




200; 







itl; 



nw- >'■ 

nw->T UBVTE M -ShowConso: 

■„ 
. 
nw->Type = WBENCHS 
nw->FirstGadget ■ » iadpw 

r.eckMark » 0; 
nw->Screen « 0; 
nw->BitKap s 0; 
■ 

sight i 

MxWidth = 640; 
"ixheight ■ 200; 

window - OpenWindcv. 



T_REFRE5H; 



dw exit : 



:Jow| ; 



/* Console* ■ i string to the 



void 
I 



iaol»Write(UBYTE 'string, int length) 
struct IOStdBeq ■ 

:'_-ateStdIO(n>yPort ) ) ) 



i 

puts I "Unable to 
goto cw_exitj 

I 

nag->i.-' :■ 



■r.sole. 






24 AC'S TECH 



. JJnitj 

'■:■ .. ■ 

(APTHI5' 

ngchf 



■ 






--bet of characters from 



• 


int I' 




it;-: 


, 


■ 


sole.'*; 


■ 


... -;vice: 



:_Unit; 
«D_BEADj 

■ 

»h; 






>r and cleat the screen. •/ 



■ 



' 



HOKi 



■ IOStdReq *msgl 

■ 

i [4 I "ESC - ); 

■■*..-. ij. .- 
mask: 

mask 

. -»fl».«nj(bd»..n_Pri, 

■ ' . 

■ . ■ 

. 'x"JG)msg->io_Device. oust ?.-19): 
■ 
uwtoa( (IW 1 j_Cormund\ mask[Ii 

igs, mask|UI'9>; 



ubto.-. 

ultoh 

-s:t ■ re 



■ 

■ ' : 

kll61»9) : 



■ 



D ; x < 19 : x - • I 

■ . ! 

ICa: ". -II; 

MOVE_CURSO: 

Consoii--. 

H0V8U 

HOVE.. 
HOVE 

H3VE_CURSOB t) : 

■■•■■'. 

EBASE_EO: 

•.-?ys I 

if f bufforlOl I 

ConsoleWritetten^ 
ConsoleWriteUi 

er| ,- 

Conso 

; 
ClearQualifieraO; 

toil x = ; buffer [x] !« j x.. | 

■ 

if t moves;. 

I 

'■ . ■ . . 
I else I 

■■ 



■ varacteri 

■ I 
lone r.-im- 

IECLASS_RAWKEY, 0,0, 



Tbui: 



■ 
i • 
lev. NULL; 



RawKeyConve: . (STRFTR) 

4L, 0L| ; 



Voiume 2, Number 3 



25 



. : 



■ 



•0': 
MUVE^j ; •2"; 
MOVE(4] = -6-; 
MOVEt5] i '1'J 
MOVE_CURSC :- 
ConsoleWriteKUBYTE # )convertbal : 



■ 



void C] 
I 



return: 

■-.:■. ■ ■: lvoid> 
•0*; 
-6' 

movei*: 
hovhlcursop ( > 

ConsoleWrueHUBYTE •)• ". 






void PrintQualirierafUBYTE "characterbuf fer) 
I 

UWWD char„qu.ilif iers; 



char_q . I 
convcrc_qualid. : , > 



■ .! 
4 & IEQUAL!FIER_LSHIFT> 



I 

t '0' 

HOVEI2) = 'S' 

MOVE14] = •$• 

moveiv 
move_cursor 

ConsoleWrmeHUBYTE a ]qiMls(0]. -I): 
lelsef 

MOVEU] . '0' 
HOVE12) = *S' 

:■• i 

move_cursor < i 
erase_eo; 
I 

if tchar_qualifiers & IEQUAL1FIERJ*SHIFT( 

I 

MOVEU I ■ ■0-; 
MOVE (2 1 = '6'; 
HOVE: I 

MOVE IS] ■ • S ' ; 
HOVE_CUHSOR<>; 
ConaolcWritel IUBYTE -Iqualali!. -llj 

... 

M0VE_CURSOR<) 
EBASE_EOL ( > ; 
) 

if <char_o>ialifiers & IEQUALIFIER_CCNrROL) 
I 



:• ■ . 


'0* 


mdvec; 


' ' 


MOVE. 1 




'• -■ 




■■ 








HOVE; 


•0'. 


hovf;. 




move; I 




HOVE[=. 


*5*j 


HOVE_CURSORO. 


ERASE_EO: 



. 



if (char_q. ', IECUALIFIEK 

1 

•0-; 

•8'; 

: 'S*; 

•S*: 

MOVE_CURSOR ( I ; 

ConsoleWritedUBYTE *lqu.. 

)else< 

HOVEIH « '0' 



■■•• 
HOVE|5| . '5' 
MDVE_CURSOR ( \ 
ERASE_EOU)j 



i£ <char_qualif iers t. I£OUALIFIE£_RALT) 



■' 


'0' 


MOVEI21 > 


'9' 


HOVE 


•S' 


move; 


■ ■ 


MOVE_CURSC 


- 


Consr 




lelsel 




HOVE 1 


•0' 


HOVE[2| . 


•9- 


HOVE ; 


•5' 


HOVE|5| ■ 


'S' 


MOVE_CURSORn 


EPASE.EOLOj 



■ . 



if lchar_qualif iers k IEQU 

( 

MOVEIl) , 'l'j 

HOVEI21 = '0* 

M0VEI4' 

MOVEiS; 

MOVE_CURSO!U ) 

ConsoleWritet IUBYTE "Jqu 

tclsel 

hove;: 

HOVE12I = '0\- 

'5'; 

■ ': 
MQVE_CUR£OFI ( ) ; 
ERASE^EOLO; 
I 









if (chJ 



f. I EQUAL !■ 
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I 

MOVEI 1 

MOVE I : 

MOVEI-. 

MOVEI^ 

M0VE_CURSOR 

Conso; 

MOVE!'. 

movei: 

MOVE!-; 
MOVE151 = ' 
MOVE_CURSOR 

■ 



' ; 



void C . 
1 




■ ■ 
" 
MOVE[4] = 'S't 

"■ ■ ' 

MOVE_CUBSOR(); 

ERASE_EO: 


MOVEI 1 1 * '0'; 
MOVEI. 
MOVE 1 ; 
MOVE|5I = '5'; 

M "■ ">f ■ i ; 


MOVEI1I = -0-; 
MOVE ; . 

MOVEI 4 ) = '5' J 
•V; 

ERASE_EOL(]; 


MOVEil] = '0*1 
M0VEI2] = ■&■: 
MOVE |4 
MOVE. 

M0VE_CURS0RO ; 
ERASE_EO:. 


move;: . •()■; 

MOVE,*. '9'; 
M0VE(4) * -S-; 
M0VE(5] : '5'; 
MOVE_CURSOR ( ) ; 
£RASE_EOU): 


MOVEI 1) « •:■; 
H0VEI21 - '0'; 
M0VE[4] ; '5'; 
MOVEtSI ^ '$'; 
MDVE_CURSOR ( ) ; 
ERASE_EOL(); 


MOVEil] . -1' 
M0VE[2j 
M0VEI4) 
M0VEI5] ■ '5' 





, -1) 



> ; 



.codetUBYTE •<-.' 



■ ■■•:••■ 



■ 



(int 



I. beginir :,q ; x < 2 j x-. 

I 
beginir 

r.g = (UBYTE • ) st rchr I tchar *>beo 



>ng I 



begin:: 

ending = (UBYTE •)strchr( (char '(be-; 
tint i semicolon); 

::ng ) 
goto cc_exit; 

temp ■ 'ending; 

•ending = iubytei 0; 

rtnval = (DWORD) atoll I char •(beginingl; 

•ending s temp; 



■nvall; 



UWORD convi 
I 



'UBYTE -string* 



Lnt x; 

char semicolon i 

UBYTE 'begining, -ending; 

UBYTE teirp; 

for I x ■ 0. bt- ; ng ; x < 3 1 x*« 

begining**; 

begining ■ (UBYTE Mat rchr I Ichar -Jbeg.: 
•"<ni colon) i 

I 

begin 

■ strchrl ichar • 
(intlsemi colon) ; 

lending I 

eomp = "ending; 

"ending = (UBYTE) 0; 

rtnval ■ (UWORD) atollichar "(begining); 

"ending = temp; 
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KM Memory 
Management, Inc. 

Amiga Service 
Specialists 

Over lour years experience! 

Commodore authorized lull 

service center. Low flat rate plus 

parts. Complete in-shop inventory 

Memory Muniigi-nu-nt, Inc. 
396 Washington Street 
Wellesley, MA 02181 

(617)2.17 6846 



Circle 108 on Reader Service card. 









(decimal), • 



i 



•asm 



pub: . 



_ubtoa: 

movOT.l do--: 

movoq 
15 move.b 

dbra 

moveq 
2S diw no, dO 

swap 

mvt.i 
swap dO 

dO 
dbra dl . 2$ 
movem.l (sp).,d 
rta 

■endas* 

u - Com- 

(decimal). " 



■ 



lam 



UWI : i: 



public _uwtoa 



and.l •$] 



-.:".-.-.; 




3S BOW 


■ 


dbia 




moveq 




. 






dO 




1530. dO 


nova.b 




swap 


dO 




dO 






ITOV6B1. ! 









lend i - 












movem.l 



or.b 

.tt(> . b 
ble. s 
oddq.b 

movem. 1 

" t Iaj a 



d2.5S 

■ 



All liftings and necessary files for 

Understanding the Console Device 

can also bo found on tho AC's TECH 

disk. 



Ploaso write to: 

David biackwell 

c o AC'S TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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AMAZING COMPUTING 

• ".i mi 

Highlight, imt.jj. 

'the Big Iliin in DIP.* . Ji-kii-nmNiJimn^. 

RMkinJ MaiaU 

'IN* Amifj Dnklop I'uM.. ti.r . < .g, J. la Srrvhr Bureau. ' 
bv l.tfin Sinner 

M\m trmlwroHM 51 »'.(.'■. «n nnpcmnw -m 

In atlaih J kiiJ did, hi v.iur A '■■I. K I 'in M. Kul—ti 

'All In One." program. ln".l.i,™i (•. K"i*.1vi».i 

Mo*,Iumt«t| 

HwMtghN include 

Mi,, rim na-,'4-nint h« Chuck Kaudcau. 

-COTV.'acvmprrhcnvir k.ik at Irnnnln. > honril ilnn 

II \\l I 
l«urj K I Xi ■ ul h ihnaid 

"PUd to * npvtrw by Ji*inStnnce 

'Protc.ional Page ID." i"'.--,-. , .-npleW arid tltiU 

(■in'r— <«ul jV-Hit [.i*i.«ln..i: p.*- Lagr bv Rcl Bcoiila 

. i m 

"lltniMkr- ■■ "'Mrili 

(mm ImpuKr by I 'ink M. Malsin 

"Proper Grammar, j mi ok a .unprelwnmr -pcllin* and 

yimnur ihctkrr bi Paul 

rwSMM ■ wtiy in lh» wort procwaii 

pubuahana- Miltwarr law. bv liihn Sirmrt 

Alto. n*Mlh'l Su«»mer CIS co.naa)r! 

- 
■ 
"Allrrlma,. r .ifvI .penal rlteit. t.ir soul luxnc 

ladrua la minute. In 1 1 <m m Minn 

1»i* letry Bnanl Shrm ■ . I. m Bryant "how 

arcirl wwo."!- hw pmdu. ~* low laainc< lrlr.inoeta week 

are Ihr Amiga ami the V Jo> Iimm 

-IndcrMaiidingGenloik. - .1*1 

"Super * Meet, the Amia-. man wUh 

ih.-a.1iliri.eiu* A-niea grapeiM. I 

•1 i-jWi jib Good -nh BAD. jr.-...,. nf< rolau. s,Hh. at. s 

iluk ifWl/n pn*0<m K K. k v 

AU». AC continue, the cilcn.ivc coverage ol the Summer 

TTTth-rfMri»1 

n«vmi 



IuMm 'i- Iva 

■II. (.4,1-. 



■ Pipe, rmioional" . ■ 

'lumr Bullrr lin-Oll- ,n ,-nm -™ ,.t tram. Killer. K 

■or-i. UdtUnri 

"DynaCADD.- ^ n HnlUtd 

I'Ui 

.\lu J{i»iu"jlnnw 

IMI 
Super June [overage (torn AuMralii arwl CM.n Jti 

• 

IIIqMjJiIi .1-1..:, 

-ArlDepar1>nentPro.t«.i.nai.-arr..rv. . i 
I mllCdnm 

Shr.»Make,.-N-i..v,1J.-^i. Tl 
"AH andlhe Amiga." I , I 

rim 

An ARcw double leatuir and j ipnul education an lion 

Hi«tililKt- include 

'Connecting "l d.i Amiga Id the Sharp Vt ira.d 

'Fpaon KA flit Bed Scanner." BO bl Willi 

Impao Vi.lon la." -i -i. .,. 

1 -.ml. M.M.Nn. 
i s \ Mrg> Mtdirl Kj.n. - ■ mini pi I 
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In the lasl two articles I've discussed libraries, macros, and 
several of the internal routines. Now it's time toexplain one of the 
Amiga's best features — graphics. Just as in Basic, graphics pro- 
grams usually start with a SCREEN and WINDOW command 
Unfortunately, however, it is not quite thai easy. You must give 
the Amiga a list of your SCREEN and WINDOW specifications 
(usually called "parameters") and, if this list meets the Amiga 
criteria, it will create a SCREEN and WINDOW and let you know 
where they are. Now let's write a simple program, 1 isling 1, that 
opens a SCREEN and WINDOW and then draws some graphics. 

SCREENS 



& 



of the Intuition library, we can now open a screen with the 
OpenScreen sub-routine. The address of our screen data 
("myscreen") is stored in register al; tin- library location goes in 
a6 (generally any library location gets stored in a6>, and we JSR to 
the OpenScreen offset. If the routine can't open a screen. dO will 
contain or .-Ist- it will contain the address of the Amiga screen 
structure (Mb bytes of information - sec Table 1). 

WINDOWS 

We'll also have to open a WINDOW. The minimum re- 
quirements to include are: 
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If you look near the end of Listing 1 you will see a section called 
"myscreen" where this data is located. The "dc." means that this 
location in memory has the following values and is "b". "w", or 
"1" in length. Toopen our screen, all we need to pass is the location 
of this data as "mvM.mir Twoofthedata, "depth" and "custom 
screen", were defined at the beginning of the listing in the 
"equates:" section. This makes it easier to change values that are 
scattered throughout the listing since they will always have the 
value defined at the beginning. 

The sub-routine for opening a screen is located in the Intu- 
ition library, so we'll open that library first. Knowing the location 



The window is opened using Intuition's OpenWindow routine. 
Since the "screen" information is still in dO, we can move this to 
the screen location (»30) in our window data. When the routine 
has executed properly. dO will contain the window structure 
location (128 bytes of window information — see Table 2). 

FLAGS 

But what about those IDCMPand window "flags"? They're 
merely numbers that tell the computer what type of window you 
want and how you'll stay in contact with Intuition. They can be 
in the "equates:" portion of the program or actually combined 
into one value. These flags are: 
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For window flags you could use: 

dc. 1 BORDERLESS! ACTIVATE (if defined in -equates:") 
or del S1800 

Once wi- have the window information, one major piece of 
information can be obtained— the window's RastPort (rp>. This 
area of 100 bytes (see Table 3) is located 50 bytes away from the 
window address just returned in dO. The RastPort includes all 
pen colors, line patterns, and area patterns information. Its loca- 
tion is required in most graphics sub-routines so we might as well 
get it now. 

A GRAPHICS DEMO 

Let's review the entire program. Listing 1. In the "equates" 
portion J AMI, JAM2, COMPLIMENT, and INVERSE refer to the 
way text is written on the screen. We'll experiment with this in a 
future article. The "offsets:" portion includes the offsets for the 
Exec, Intuition, and Graphics libraries along with a brief de- 
s< npiion of what must go in the required registers. Finally, I've 
assigned the variables "across" and "down" to registers d6 and 
d5 rather than reserve space for them at the end of the program. 
An) lime you can use registers instead of memorv locations your 
program will run more quickly. 

The first command line moves the SP address (the current 
address) to "stack" and saves it there. At the end of the program 
we'll put that address back in the SP and everything will be as it 
was. Next, the Intuition and Graphics libraries are opened, then 
we set up the screen and window; save the RastPort location, and 
use Sell >r\ld to set our text Style to) AMI. 

The graphics demo sots the APen (foreground) color to 3 
with the Set A Pen routine. Next we'll fill a 60x60 block with this 
color. When you us*- WritePixel to PSETa point, registers dO and 
dl need to be clear of everything except the coordinates. Since 
we're only changing one word, you can make sure the other word 
is a zero by LXTending the sign through the last 16 bits. Remem- 
ber that the sign of a positive number is 0. This could also have 
been done first with MOVEQ «),d0 since that clears the entire 
register. ADD will increase the contents of a register by the 
amount designated; ADDQ (or SUBQ) can be used if this value is 



from 1 -8. TheCMPcommand will compare a value and a register 
or two registers, and set the conditional flags according to the 
result 1 1 til.- two values are not equal,aBNE (Branch if Not Equal) 
command will branch; BNE.S means it is a short branch (-128 to 
• 127 bytes away). 

Fill_rectangle first changes the pen color to 4 and then uses 
RectFill to draw and almost instantly fill a box with color. The 
draw_circle routine first changes the outline pen color to 4. There 
is no ROM routine for this, so we have to go directly to the 
RastPort and put a 4 at the OPen location 27 bytes from there. 
You'll see that the other pen routines work this way if you 
disassemble their commands. The DrawEllipse routine is then 
used to draw a circle by making the two radii in d2 and d3 the 
same. After the APen color has been switched to 3, the Flood 
routine fills the circle just as in Basic's PAINT command. ModeO 
means to fill the circle until the outline color is reached. 

The last routine draws a diamond within a diamond and 
then fills the spaces with different colors. After setting both the 
OPen and APen color to 2, the Move routine moves to location 
250,25. If you didn't use Move to go there, there would be a line 
from your last drawn location to that point. PolyDraw connects 
lines from a table of coordinates (PolyTablel and PolyTable2> at 
the end of the program. The table location goes in register aO and 
the number of pairs in dO. Note that you have to repeat the first 
pairas the last pair to connect the lines. Then the computer moves 
to 250,45 and draws the second diamond. After filling the outer 
space with the APen color, the color is changed to 3 and the inner 
space is filled. 

The "mousepress" portion actually checks just one bit(BTST) 
in location SBFEOOI. As long as bit6 in this location is 1, the LMB 
(Left Mouse Button) has not been pressed and the routine branches 
back; when you press the LMB, bit6changes to and the program 
continues. Close the window with Intuition'sCloseWindow rou- 
tine and close the screen with CloseScreen. Windows, screens, 
and libraries are normally closed in the reverse order in which 
they were opened. The original starting location is placed back in 
the SP register and the RTS (ReTurn from Sub-routine) takes us 
back to the CLI. Closing a screen before closing a window will 
usually cause a crash. 

At the end of the program six locations were reserved as long 
words (del) for variables, followed by the two libraries we 
needed, the screen and window parameters, and the two polygon 
tables. Copy or assemble this listing to your PROGRAMSdisk (as 
discussed previously in Part I of this series) as GFXDEMO.ASM 
and GFXDEMO. Run the program from the CLI as GFXDEMO; 
pressing the LMB will return you to the CLI. Try changing parts 
of the program, especially the window flags and IDCMP flags to 
see how they affect the window; you might even want to add a 
"my_tille". 

USING ARRAYS 

This article is also a discussion of arrays— that's the Basic 
command DIM(X.Y) which sets aside a block of memory X bytes 
wide and Y bytes deep. Since DIM or arrays usually start at 0, the 
actual size we're reserving is (X+ 1 )"( Y+ 1 )- 1 bytes. You do this in 
assembly language with the Exec routine AllocMem. The size, in 
bytes, of the array goes in register dO and the type of memory in 
register dl. Memory types are: 
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Resource — macro disassembler 

Resource V5 is an intelligent interactive disassembler lor the 
Amiga programmer Resource V5 is Mwdmgiy last, disassembling 
literally hundreds ol thousands of hnes per minute from executable 
liies, binary tiles, disk tracks, or directly from memory. Full use is 
made ol the Amiga windowing environment, and there are over 
900 functions to make disassembling code easier and more 
thorough than its ever been 

Virtually all V20 Amiga symbol bases are available at the touch ol a 
key. In addition, you may create your own symbol bases. 
Base-relative addressing, usmg any address register, is supported 
lor disassembling compiled programs. An Amiga hunk types are 
supported lor code scan. 

Resource V5 runs on any 680x0 CPU. but automatical^ delects the 
presence of an 020^030 CPU and runs faster routines it possible. 
Resource V5 understands 68030 instructions and supports the new 
M68000 Family assembly language syntax as specified by Motorola 
(or the new addressing modes used on me 
020/030 processors Resource V5 and 
Macro68 are among the lew Amtga programs 
now available that provide thts support. Old 
syntax is also supported as a user opbon. 



An all new online help facility leatunng 

hypertext word indexing is included. This 

enables you to get m-depth help about any 

(unction at the touch ol a key' Resource V5 

includes a new. completely rewritten manual 

leatunng two tutorials on disasssemWy. and 

comprehensive instructions lor utilizing the power m Resource VS. 

Resource V5 will enable you to explore the Amiga. Find out how 
your favorite program works. Fix bugs m executabies Examine 
your own compiled code. 

"II you're serious about disassembling code, look no further!" 

Resource V5 requires V1.3 or later ol the Amiga OS. and at leasl 1 
megabyte o( ram. Resource V5 supercedes all previous versions 

Suggested retail pnce: US$150 NEW VERNON- 



Buy Macro68 

and Resource 

together and get 

S30 off! 



Macro68 — macro assembler 



Macro68 V3 is the mosf powerful assembler lor the entire tine ol 
Amiga personal computers 

Macro68 V3 supports the entire Motorola M68000 Family 
including the MC68030 and MC68040 CPUs. MC68881 and 
MC68882 FPUs and MC68851 MMU. The Amiga Copper is also 
supported, eliminating the need for tedious hand coding ol 
'Copper Lists' 

This fast, multi-pass assembler supports the new Motorola 
M68000 Family assembly language syntax, and comes with a 
utility to convert old-style syntax source code painlessly. The new 
syntax was developed by Motorola specialty to support the 
addressing capabilities ol the new generation ol CPUs Old-stylo 
syntax is also supported, at slightly reduced assembly speeds. 

Most features of Macro68 V3 are limited only by available 

memory. It also boasts macro power unparalleled in products ol 
this class There are many new and innovative 
assembler directives For instance, a special 
structure offset directive assures maximum 
compatibility with the Amiga's interface 
conventions. A frame offset directive makes 
dealing with stack storage easy. Both lorward 
and backward branches, as well as many other 
instructions, may be optimized by a 
sophisticated N-pass optimizer Full listing 
control, including cross-referenced listings, is 
standard. A user-accessible Me provides the 

ability to customize directives and run-time messages Irom the 

assembler. 



fingerTalk — fingerspelling tutor 

lingerTalk will help you communicate with hearing 
impaired persons, and is useful anytime silent 
communication is needed. This interactive program will 
teach fingerspelling (hand-signs lor letters and numbers) to 
both adults and children. There are 5 different modes to 
help you to learn quickty. Suggested retail pnce: USS35 



Macro68 V3 is fully re-entrant, and may be made resident An 
AREXX"* interface provides "real-time* communication with the editor 
ol your choce A number ol oVectives enable Macro68 V3 to 
communicaie with AnvgaDos" External programs may be invoked 
on oither pass, and the results "lterpreted Posabty tho most unique 
feature of Macro68 V3 is the use ol a shared-library, which allows 
resident preassembled include files for inoetfcbly last assemblies 

"It has probably the largest sol of directives ever seen r\ an assembler, a 
nice macro facility, pre-compiled resident nduocs. ARexx support, the 

best customer support anywhere, and it's last' — JLM. Byhaha. MS 

"Very well-wntten. high performance development tool'* -WHM, 
Houghton. Ml 

Macro68 V3 is compatible with the directives used by most 
popular assemblers. Output file formats include executable 
object, linkable object, binary image, and Motorola S records. 
Macro68 V3 requires at least 1 meg ol memory. 

Suggested retail pnce: USSt50 ^ VERSION*. 
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Public [SI] - either fast or chip nwiory 

Chip <52 > - uses the lower 512K (graphics and soundl 

Pant <S4l - above the first M2K 

Clear i Si 00001 - used with the above to clear all values to 

After the AlIocMem routine, dO will contain the address of where 
the computer has stored this memory for you. Since the next 
program needs two arrays, these locations get stored in array] 
and array2. A returned value of means the computer couldn't 
reserve enough space for the memory type you wanted. This 
routine is part of the EXECMACROS.i included on this disk. All 
allocated memory must be released using the Exec routine 
FreeMem— also part of EXECMACROS i. 

A FASTER PSET 

Before we review the next program, one moreitem. In Listing 
1,1 usedWritePixeltoPSETa point. Unfortunately, this frequently 
used routine is also one of the Amiga's slowest. Let'sdiscuss how 
PSET actually works and then write our own routine — longer but 
quicker. 

Colors (or their PALETTE) are stored in bitplanes on the 
screen. Each bitplane is the size of the screen and there may be up 
to six of them. Think of them as individual arrays with each cell 
in that array containing the value of one bit of the color number. 
The first bitplane holds the first color number bit, the second 
bitplane holds the second color number bit, etc. If the color 
number is 23 ( 101 1 1 ), the first bitplane will have a 1, the second a 
1, the third a 1, the fourth a 0, and the fifth a 1. Now, first of all, 
wherearethebitplanes?ThereisabitmapaddressintheRastPort, 
four bytes in (see Table 3). The bitplane addresses themselves 
begin eight bytes from the bitmap address and are long words 
(every four bytes). To obtain all these locations use: 



BASIC 
FPfc.WINDC*H8> 
HAPfc.PEEKt.IRPfc.4l 
PLANE1 1 ■ PEEKL ( HAPfc • 3 1 



ASSEMBLY 
HOVEA.L RP.A1 
MOVEA.!, 4(A1>.A1 
HOVE.L 8IAH.K 
HOVE.L 12(A1|.PLAKE2 ...etc. 



This would continue up to plane5 or plane6 for HAM. Next, 
where is any point in relation to these bitplanes? In a low resolu- 
tion screen each bitplane and the screen itself are 320 bits across 
and 200 bits down. Since eight bits make one bvte, there are 40 
bytes (0-39) across — so the byte at the start of a row containing the 
(across,down) location is 40'down. The byte within that row 
must be across\8 because there are eight bits per byte. Since bits 
are labeled 0-7, AND the across distance with 7 to get a number 
within that range. Unfortunately, bitsare numbered from right to 
left so we have to subtract this value from 7 to get the actual bit. 
The location we'll work with is the bitplane address plus 
40*down plus across\8, and we have to test the computed bit 
within that byte. Fortunately, there are three commands that will 
help: 

BTST - test a color bit to «e* if it il or 1 
BSET - sot a bitplane bit to 1 
BCtP - clear a bitplane bit to 

This must be repeated for each bitplane. Although the routine is 
a lot longer than WritePixel, the built-in ROM routine must check 
so much else (window placement, etc.) that this routine executes 
much more quickly! 



AN ARRAY DEMO 

Now for the program. Listing 2. We'll start off with an array 
161x161 (0-160)and put the value31 in the centersquare(161* 161- 
l)/2. Then the program starts modifying the array by going to 
each cell and adding up the sum of its eight neighbors plus itself. 
The result is divided by 8 and ANDed with 31 to keep it within 0- 
31. This new value is put into the corresponding cell of array2. 
When all the cells in array 1 have been checked, the value of each 
cell in array2 is put back in arrayl and each cell is PSET on the 
screen according to its new value. This continues until you press 
the LMB. The picture starts out very small in the center of the 
screen and expands into an egg shape. 

After defining the "equates:" and "offsets:", the three vari- 
ables "sum", "across", and "down" are equated to registers d~, 
d6, and d5. The program then opens the libraries, screen, and 
window; notice how macros let us doall this using onlv four lines 
After the draw mode is set, the five bitplane addresses are 
computed. Once we've loaded the address of variable bitplanel 
into register aO, we can automatically increase that address with 
(a0)+. The "+" will increase the address by the MOVE amount 
such as MOVE.B by 1, MOVE.W by 2, and MOVE.L by 4. 
The opposite of this would be -(a0) in which case the address 
would be decreased by 1, 2, or 4. Increases (postincrement) 
happen after the MOVE command, decreases (predecrement) 
before the MOVE. Then space is reserved for the two 26,000 byte 
.irr.iw 

After storing the location of arrayl in a4, the center of the 
array (12960) is stored in dO and the value 31 stored at that 
location. The 0(a4,d0.w) means to add together the value 0, the 
value in a4, and the value in dO. The value of array 1 is again put 
into a4, and array2 intoa5. Each value is increased by 1 <>2 since we 
are actually starting at location (1,1). In fact, we'll always stay one 
cell away from the edges since we want to change/check values 
one square out in all directions from the cell we're in. If we started 
right at the top row, we'd be using squares outside the array- This 
is also why "down" and "across" are only 158 during the first 
pass. 

Whatever cell we're in, the cell -162 bytes away is the cell one 
row above and one to the left; thatcell's v. ilue is put in "sum". The 
cell just above us, or -161 away, and its value are added to "sum". 
the cell above and to the right is-160awav and its value is added 
to "sum". The cells -1, +1, +160, +161, +162 bytes away, <md the 
cell itself all have their values added to "sum". "Sum" is divided 
by 8 using a shift command and then ANDed with 31 to keep it 
within the color values. 

Shifts are a rapid way to multiply or divide by powers of 2. 
Each shift of a register to the right will divide its contents by 2and 
each shift to the left will multiply it by 2. Shifts only apply to data 
registers. If you specify a shift number, it must be between 1-7; if 
you use a data register to hold the number of shifts, it may be 
between 1-63. The bit that is shifted out of the register usually 
goes to the carry flag. In general, the three types of shifts are: 
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left bit goes '. 
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left bit stays I 
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left bit goes tc 
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Only a rotate command will eventually go full-circle back to its 
original value. 
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Once the new value has been computed it's stored in arrav2 
and the location is automatically increased by 1 (MOVE.B 
SUM.(A5+)(; LEA is used to increase the location inarrayl by 1. 
The DBF command (Decrease, Branch it Faults) means to keep 
decreasing the down value and, as long as it is or greater, branch 
lo L2 — a very quick counter 

At the end of the first pass the array locations are again put 
in a4 and a5. The first contents of each array are compared, and it 
they're the some, the program branches. If they're not the same, 
the contents of array 2 are moved to "sum" and array I. Note the 
use of predecrement addressing (-(a5) and -(a4)). The qpset 
routine sets the points at (at. ross.down) with the color value in 
sum. To center the display of 160x160, 1 added 80 to the across 
location and 20 to the down location. The down location is 
multiplied by 40 through the use of shifts— down'32 • down*8 = 
down"40. Since the screen depth is 5. there are five loops within 
this routine to check each color bit and set/ reset the correspond- 
ing bit of each bitplane. At the end of cjpset each array counter is 
increased by 1. 

When the second pass is finished, the program checks to see 
if you've pressed the l.MB. If not, it will branch back to showit. 
There are two "showit" locations. The tirst one always puts #31 
in the center square. You can change the program by putting 
semicolons in front of those tour lines and removing the semico- 
lon from the next "showit ". There is also a line in the II routine 
where you can remove me semicolon for a major change in the 
display. 

The program ends by first freeing the memory in array 1 and 
arrav2 with the Exec routine I reeMem. If you don't do this, thai 
memory stays reserved until you power down. Next, the win- 
dow, screen, and libraries are closed in the reverse order in which 
they were opened. The data at the end of the program reserves 
space for variables/ defines libraries, and sets window and screen 
parameters. 

Feel freetoexperimentwith this program fry just adding Up 
the four squares that border the center cell and divide the result 



by 1 1 LSR.W »2,SUM). Add a value other than I to the result or 
eliminate using the center square. The variations are endless 
when working with arrays— you can set your own rules in almost 
any possible combination. Copv or assemble this listing to your 
PROGRAMS disk as EGG. ASM and as EGG. 

INTUITION MACROS 

Now let's write some macros that will make using screens, 
windows, and graphics a lot easier. Both of these macro tiles, 
along with the EXECMACROS.i are included on the magazine 
disk. Since the Intuition library is used first to open screens and 
windows, it makes sense to Mart with it. In Listing 3 I've started 
with the onsets for the various Intuition routines and their 
register requirements. The "equates:" portion will help in setting 
up your screen and window requirements. For a 640x400 screen 
you could include either $8004 as the mode or type 
HIWSSaNTERLACE (the "!" means to logically OR the values for 
HIRES and INTERLACE). A borderless window with sizing, 
drag, depth, and closing gadgets could be described in Flags as 
S80F or as 

In both cases, the second met hod ta kes longer to type bu t is easier 
to read and change it's your choice 

The macros are pretty obvious. OPEN WINDOW will insert 
the screen location into "mywindow"; once it has opened the 
Window the RastPort is stored in RP and the VtewPort is stored 
In \T. The Viewport (Table 4) Is used mainlv when you want to 
change PEN andPALETTEcolors.CETBITPLANTS will storesix 
bitplane locations, although the values are only valid up to the 
DEPTH you've selected. To make it easier, all of the storage 
locations are within the macro so you don't have to worry about 
them when writing your program. Copy or save this listing to 
vour ASSEMBLER disk (as discussed in Part I of this series) as 
INTMACROS-i. 



TABLE 1 
SCREEN STRUCTURE (346 BYTES) 



POINTER TO HEXT SCREEN 
4 POINTER TO FIRST WINDOW 
8 LEFT EDGE 
10 TOP EDGE 
12 WIDTH 
14 HEIGHT 
16 M3USEX 
18 MDUSEY 

INTUITION FLAGS 

POINTER TO SCRH 
26 DEFAULT TITLE 

30 BAR HEIGHT 

31 BAR VERTICAL BORDER 

32 BAR HORIZONTAL BORDER 

33 MENU VERTICAL BORDER 

34 MENU HEIGHT BORDER 



20 
22 



35 



36 


;::.:■ 


40 


P01N" 


44 




84 




184 






LAY 


326 


POX. 


330 




331 








334 





ma 
/CTURE 

1CTURE 






GRAPHICS MACROS 

The major routines, their offsets, and 

register requirements are listed first. Pen 

colors are set using FOREGROUND or 
BACKGROUND. OUTLINE sets both the 
outline and foreground pens to the Same 
color as required by the Flood routine. 
Whenever possible, I like to use Basic com- 
mands and format as macros; I find them 
easier to use and the macro requirements 
easier to remember. That's why I call the 
macro using the Mine routine LOCATE 
and the one using VVritePixel, PSET. 

My QPSET is the fast PSET we've 
already discussed. Both PSE T and Q\*SEl 
allow you to include an Xoffset and Yoffsct 
to center the picture; also both assume that 
"across" and "down" will hold the X- and 
Y-coordinates. QPSET requires that DEPTH 
be equated to a value (i-t>). the color to be 
passed with the macro, and is onlv tor a 
low rcsohi lion picture {320x200 or 320x400). 
How would you convert this macro to show 
a high resolution (640 across) picture? 
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I'AU-Tl I uses the I oadRGtM routine to change the actual 
colors of the individual pens. We'll talk about this macro in the 
next program. PCLS will clear the screen to colorO or a color 
passed wilh the macro. LINE draws a line connecting XI,VI and 
X2.Y2; the color is an optional value. BOX will draw a rectangle 
beiweenXl.Yl and X2,Y2;again,colorisanoptional value BOXF 
will draw a box and rapidly fill it using the RectFill routine. 

CIRC I E and ELLIPSE both use the Draw-Ellipse routine. If 
the two radii are the same, the result will be a circle; the color is 
optional in both macros. PEN will change the color of an Indi- 
vidual pen*. This change will also apply to anywhere thai CC-loi 
is already on the screen— useful for fade-in/out or animation 
PAINT uses the Flood routine to fill .m area with the foreground 
color. The macro assumes that you want modcO (fill until you 
reach the outline color) unless you pass a "I" in the macro 
Finally, POLYGON will conned the coordinates listed in a table: 

the color is an optional value. Copy or save this listing on vour 
ASSEMHI IK disk as OFXMACRt >s I 

Try re-doing listing I using as main o! these macros as 
possible to replace the routines in the listing. I would Start with 
the graphics macro, first and then substitute the Intuition ones 

When you feel comfortable with these macros, (eel tnv to rename 
them, modify them, or make Whatever changes you want. |usl 

remember, the more complicated you make them, theharder they 

are to remember a week later. 

PASSING VALUES 

Next I'll show you how to pass values from the CU to \ our 
program, make your own semi-random function, and change I he 



TABLE 2 
WINDOW STRUCTURE (128 BYTES) 



6 EDGE 

■ ■ 
10 H! 

12 MOUSEX 
U MOUSEY 

TJH WICTTH 



L6 

IB 

24 

\l 
40 



54 

56 
57 
58 



"R£ 

:tl£ 

first requester pointer 
double click requester 
count of requesters 
scree: pointer 

cw pointer 
left border width 
top border width 
right border width 
bottom border width 
border rastport 



62 gadget: 

66 parent <open/cix)se> 

70 DET \ 

DATA 

78 POINTER SPRITE HL. 

79 POINT! 

80 PO:: 

81 PC 

SERPORT 

90 PC 

94 POINTER TO IMESSAGE 

98 DEI. 

99 BLOCK 

100 check::: - 

■ 
108 



tOZERO HE! 

116 EXTERNAL DATA PC. 
120 USER : T7EH 

■ .. ■ . 



color palette. The demonstration program is a version of the 
"Demon" article in Scientific American, where cells devour other 

Cells Ol a lower value. As in the previous program, I'll use a 
lr-)Xl6l) array centered in a low resolution screen 

In the "Demon" program the four neighborsaroundacellare 

ed to see II any ol them has a value one greater than the 

center cell. It so. the -enter cell is "eaten" (replaced) bv the new 

valueand the next c.lliscluvked ( ellvalueswraparoundsothat 
the maximum value plus 1 equals zero. The default maximum 
value is 15, but you may pick any number up to 31 I lowever. 
valuesabove20tendtoradeoutquickl} since the size of the array 

isn't thai large. Initially, I'd experiment with values from 10-20. 

As cells devour each other, the pattern of the random array 

becomes more regular and may gradually change to spirals that 
take over the entire picture. 

Since the "Demon" program needs to know the maximum 
cell value you want to use, we'll pas. that value ( 1 -.11 ) from the 

CU along with the program name. Register aO is always a pointer 

10 the addre-s where anything altera CM command Is stored (as 

an ASCII character string) and register dO contains the number of 

characters. 

follow the "gel ( 1 1 value" routine in Listing 5 and you can 
see that the first step is to save both the string address and number 

meters In separate registers. If (he number of characters 

minus lis zero, then all you typed in was the program name, and 

the routine automatically passes a default value of 15 to the 
variable level*. When there is another character though* it must 

be a number, so subtract <r$30 from its ASCII value to get the 
actual number. 

Subtract 3 from the value in d5. If the 
result is 0, there are no more characters and we 

have only a value from 1-9 to put in "lc\ 
But if there is still another character, then the 
one we ahead) have is the ten's portion, so 

mult ip iy it by in. Ml U 1 means to MULtiply 
ned values (Ml I Swill MULtiply Signed 
values), Nov. add the next character to the 
result and again subtract 0$3O to normalize the 
result Store this value in the variable "level". 



A RANDOM ROUTINE 

There is no specifu random routine 
in assembly languageso you have toadapt one 

for yourself Mine uses one of the Complex 
e Adaptor (CIA) registers at SHI I SOI 
thai normally counts events I ollow the "ran- 
dom'' routine in Listing 5 and you can see that 
the contents of SBFE801 are stored in d4; then 

l aiious Changes are made to this value. Since 
we want a random number between and the 
value in your CI. I command (or the default 
value of 1^), the value in d4 must always be 
compared with the value in "level" I he pro- 
gram keeps looping until aw acceptable num- 
ber is found I he \( »P command means No 
OIVi ation and is just a delav to keep the events 
counter "ticking''. It you have your own fa- 
vorite random routine, feel free to substitute it 
lor this one Ik- sure to keep the result between 
and level", then store the result in d4. 
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I wanted .1 different palette for the first 16 color- (0-15), so I 
used the PALETTE macro lo create a new one from the color table 
.it I he end of the program. The value of each word in the table 
represents theamount (O-F)of red. green, and blue, respectively, 
in thai pen* 'i ou can change these to an} color you wanl Notice 

thai 1 have the tirst color as 0.0,0 SO IVnO, the b.u kgTOUnd, will be 
black. 

To initiate I'ALETTE you need the VicwPorl structure lo- 
cation l.'nlike obtaining the Kastl'ort location (here is a routine to 

get the ViewPort — Intuition's ViewPortAddress. All you need to 
doUstore u^e window structure address in res^steraOand call the 
routine; res^ster dO will contain me ViewPort address. Io change 
the palette pul the Viewport address in Ml the location ol 

color table in al, and the number of pens you're changing in dO. 
Pen changes always start with Pi 

THE DEMON PROGRAM 

Now let's go through Listing 5. In addition to the routines 

just described, thereare two new routines from the Exec library 

Forbid and Permit. Forbid will stop all Other activity, mouse 
movement, etc . this will enable the program to run a little more 
quickly. Ihe opposite, Permit, frees the computer and allows 
multi-tasking 

I've added the register equate "sum" since it i> us,\i so often 
during the program Ihesi/eol thearra\s we'll USeisalsodefttKd 

DO. rhere are now FOREGROUND and PS1 I macros but, 

with QI*SI: I available, we won't use them loo ollen. They are 

used, however, after the random routine gets a value; that value 

is used to set tin Al'en and color the location. Ihe I \ec macro 

ARRAY uses the previously defined size Inn-serve memory and 



TABLE 3 




RASTPORT STRUCTURE (FIRST 40 BYTES) 
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citherstores the memory address in the location passed or branches 
if unsuccessful to the location given. 

After saving the Stack Pointer, the program computes your 
value passed from theCLI or defaults to 15. The best values t.» use 
are within the range of 10-20; below that the pattern looks mainly 
like small worms, and values above will probably die out due to 
the -.mall size of the array. The value you select represents the 
number of colors used. Whenever a center cell's adjacent neigh- 
bor has a value one higher than itself, thai neighbor can "ea t " the 
center cell by replacing it with its new value. To "wrap" the colors 
around. I is greater then OandO is greater than the highest value 

Next, the program opens the libraries and sets up the screen 
and window. Knowing the window structure, the program can 
obtain the RastPort (rp) and ViewPort (vp). After getting the vp, 
the program reads the new pen colors and uses PALETTE to 
change the colors l'hen the bitplanes are located and memory is 
reserved for the two 160X160 arrays. The random portion com- 
putes a number from to level, PSETs the (across,down) local ion 
to the color value, and sturrs this value in both array 1 and arra\2 
The postincrement mode is used to increase the array locations, 
After this, the Forbid routine is called. 

The demonstration part of this program starts at ( 1,1) in each 
array ,md saves the value there as "sum". Then it adds I to this 
value, wrapping back to if necessary. This is now the value to 
which the four neighbors touching the center cell will be com- 
pared. The cell just above is -161 bytes away I-I6lu4)) and it's 
value is compared to "sum". If it is not the same, the program goes 
to the cell just to the left (-l(a4», It, however, they are the same, 
"sum" is transferred to array2 as the new value. After its neigh- 
bors have been checked, each array location is increased by 1 
(LEA 1(a4),a4). notice that we can't combine the offset and 
postincrement modes. At the end of each row both arrays are 
increased by 2 It) compensate for the bytes not checked at the end 
of one row and the beginning of the next row. 

After examining tin- cells in array 1, the contents of arr«iv2 are 
compared toarrayl; if they re the same the program goes on to the 
next cell. If they're not the same, however, the value from arrav2 
is transferred to array 1 and the corresponding point is set using 
QPSET with offsets to center the picture. When all of array2has 
been checked, the program looks to see if you've pressed the 
LMB. If not, it repeats the entire process 

To end the program a call is first made to Permit, then the 
memory in both arrays is cleared with FREE, the window and 
screen closed, the libraries closed, and the Stack Pointer returned. 
In addition to the usual variables and window/screen param- 
eters, the program has a color table for the new pen colors. Copy 
or assemble this program as DEMON.ASM and DEMON. Run 
this program from the CLI as DEMON, adding the color value 
you want to use. if any (e.g., DEMON 16). 

Besides the changes I've mentioned, vou might want to 
modify the "get _C II .value" routine by adding another check for 
incorrect values or mistakes Try Increasing the screen size to 
interlaced (S4) and then maybe increase the array SUM to 160X320. 
Be sure to increase SIZE and the down dimensions within the 
program; with a larger array you could use higher color values. 
If you're really ambitious, add a flag that will stop the program 
and let VOU know if a pass did not change an v. ell values and the 
program is actuallv over 



NEXT TIME 

In the next article I'll combine assembly language programs 
with Basic, and show you how to use LHARC in your startup- 
sequence. We'll review the rules of LIFE, visualize some WALL- 
PAPER, and experiment with double- buffering. 
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ic.l 



ointet 



to CL-I 
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intbax- 
rp dc 



■ 

■ 
. 
■van 

,200 

.1 



:pens 
: ocr"- 



■ ■ 
mo <j.i : ■ 

- MB 

0.100 
polyt ..: 

■ 
■ 






Listing 2 



■ 



■ 



■ 

■OV».l 

i- !.- 

■ 

: ■ -- ' - 
d0.\2 



■AC 




glxbdai 








r- ' . lr 






■ 






move.! 




■p. stack 


OfMfl. . 




;Open r*q 

' 'tie 

■ 








mfiKe_' 






[■per. ■ 




- indow; 






open window 


-y* -?wl ■*. ■ indow. c 1 on«_acraen 


mavea. ! 




dO.aO 






ww.rport u 


move. 1 




;w. 


move*. : 




ip.ai 


raovo. 1 




•JamJ.dO 






■ . 







; EGO . on* 






exacnactoe.l 


■-B! 




depth 










■ 






■ 




■■ 




l 




backdrop :■ . . 




nw.acrc 






■ 


$1000 








oflaatai 












■ 


■ 




. -304 


cloaev 








■■ I 




■u* <- 




vqur 


■ 






array; 

rove. 1 

■ 



■ 
bpl.at 

j address ■ 

■ 

laddreaa i 



, laOl 



■address c: 



i locat ion 
I jaave the a.i . ■ 





1 


oove.l 


!,dl 




-•wi 


■ - 


■ 






PJOVM, ; 




»■>■'*. 1 




r-.-.-j 


» 


mov»q 


* in : out 


novaq 


•O.down i 







I 






40 



AC'S TECH 



■ 

: 
BOV. 












■ 

■ 



■ 



■ 



■ 






■ 

■ ■■ . : ■ 






■ 



1 






1 



■ 





















■ 












- ■■.'...( 




























--. 










•■1.1 






idown i 




































■ 






































• 
































• 


































■ 






























■■ 






















































. 













■ • i . 
















'■..-. 


• . 












B ■ . ' .1 












olo*«_- 






CCV4M . 1 






















■ ■ 


■ 




ClOMS 






;clofte i 


■ 












cU 












---. 1 










































. 
























bpl d- 







ivMpe 

. .■ ■-.: 







The remainder of the listings for 

Programming the Amiga in Assembly 

Language Part III can be found on the 

ACs TECH disk. 



Fol 



Please write to 
William P. Nee 
c/o ACs TECH 
P.O. Box 2140 
River. MA 02722-2140 
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a«fk|ip 



by Werthvr Piram 



ll von do Minn- programming and you need to speed up its 
development .1 Utile, tin- KM thing in do is to use a KAM-DISK t<< keep 

youi sources, your executable! and, if you can afford some extra RAM, 
even the include files A recoverable RAM-DISK surely might be youi 
Utile assurance agabul a vWl irom the dreaded GURU. II there was 1 
power failure, you could low .ill of your dies m RAM The best thing to 
make a back-up.it regular intervals and copy Iho tiles from the 
KAM-DISK to a floppy dish Even it you're lazy, this Is not too 
demanding but when you're working on .1 larger program whose 
source is broken into smaller file*, tiimgs can become pretty bonng 
1 ven worse* you can'l always remember how many flies you've 
modihed Since Ihe last back-up. 

\ script flle like thai m listing 1 might be useful. Although it does 
ku k -up only the most recent hies, it copies All the most recent files, 
Including those thai weren't even modified since the previous back-up, 
so a different solution has to be round Well, (he perfect solution is not 

t*H> far away .m^i ll comes m the shape ot the flic archive-bltl 

I ypicilly, the archive-bit should be set each time .1 Me is backed* 

up and should be cleared each lime a file has been modified.- Unfortu- 
nately, as of this writing, tin- file archive-hit is something that 

jaDOSdoesn'i deal automatically with iii.it is. while you are m 
the t 1 1 you can set it directly by typing: 

Protect filename -a 
or you can do the reverse by typing 

Protect filename -a 
but nothing more: e\ en though the Copy and the I 1st commands are 

quite flexible, especially the latter in conjunction with the I FORM \ 1 

option, you can't get iheni to lake into account the status of the file 
archive-bit nut's wh) I've come up with this iitilev.il utility. 

How to Use It 

Backup is es sen t ia l ly a copy program that is directory oriented, 
rather than tile oriented. In tad. it's intended to Work with the hies 
within a given direclqry or within nested directories You can use it 
only from the CI I by tvping: 

Backup SourceDir DeatDir [ALL] [QUIET] 

Of course. SourceDir and Destlhr are mandatory and musl both exist 
the command is executed while the Al I and QUIET switches 
ire optional and have the SajTW functionality as ot those from the 
Copy command Let's tee a few examples 



Backup 



dfl:HyDlr 






42 



AC'S TECH 



Each file within the Current directory with the archive bit still clear is 
copied todtl MyDirnnd then its archive hit Is set Information about 
the operation in progress is pnnt.il to the CU, but nested directories 

are ignored. 



Backup 



d£l:»tyDir ALL 



Sam,- as above but takes inlo account nested directories. If such 
directories don't exist within Ihe destination directory, firsl thev are 
created and then the files with Ihe archive bit not set are copied to 
them Information about the operation in progress is still printed to the 
( II 

Backup " dfl:MyDir ALL QUIET 

Same as above bin t^" information about Ihe operation in progress is 
printed to the CU, except for error messages However, if you want to 

suppress ihem. you can use redirection: 



Backup >HIL: 



dfl:HyDir ALL QOIET 



How It Works 

l Isting 2 is the source for Backup ,m^\ it's fully documented 
Rather than discuss II at some length, I'd like to point out a few things 
about AmigaDOS, but don't expect me to supplant anv documentation 
currently available. 

As to begin with, a lew words about Ihe lock, a mechanism 
provided by AmigaDOS for moving around in its file System. When 
you're locking a file or a directory, you're asldng AmigaDOS to refer 
all of your requests lo that particular file or directory A call to the 
Lock!) function takes this form 

lock ■ Lock (path string, access node), * 

where lock is ,1 pointer to ■ hlcl.ock structure returned by Lock(). 
path string specifies the file or directory you want to lock, tor example 
"dfl :MainDir /Other Oir/hn.ilDir" and aciess_modc is either 
ACCESS.READ also called SHAluEDJ-OCK because any other 

program can access it, or ACCESS, WRIT* also called 

EXCl.l M\ 1 I ( K'K because any other program is effectively locked 
out from the access lo ll 1 lowever. whatever the access_mode you 

get 10 unlock what you've locked or the AmigaDOS 
will soon become pretty messed up and you'll have to reboot to bring 
things back to normality A call to the Lnl.oekO function takes this 
form 

Unlock < lock I ; 

where lock is a pointer returned by Ihe previous .all to I ockQ Thai 1-, 
1 ix. k( land Unl.ockO must always be paired. 



If you've locked a directory, Ihen you can move to thai directory 
using the CurrentDir() function whose effect is the same of the CD 
command: 

oldlock - CurrentDlrUock); 

once again, lock is a pointer returned by the Lock() function and 
oldlock is another pointer to let you come back to wherever you were 
in the first place: 



djnnylock 



CurrentDir(oldlock) j 



Once you've locked a director)' and moved to it, you can get 
information about the Directory Type, FileName, Size, Date, Comment, 
Protection bits and so on by reading the contents of a FilelnfoBlock 
structure which is listed in the include file libra ries/dos.h. but first you 
must allocate enough memory for it: 



fib ■ (struct PilelnfoBlock •) 
AllocMem(sizeof<stnict PilelnfoBlock) 



m™? CUM] i 



U fib If not NULL then you can call the Examine*.) function to fill the 
FilelnfoBlock structure with the information about that directory: 

success ■ Examine (lock, fib); 

when lock is the pointer to a FileLock structure returned by Lock() 
and fib is the pointer to a FilelnfoBlock structure allocated by 
AllocMemO. If success is not zero then you can examine the contents of 
thai FilelnfoBlock and finally access the information you need. 
Furthermore, if you want to get information about the files within the 
samedirectory you can use the ExNextO function: 

success ■ Bxftext ( lock, fib); 

The parameters are the fame as those for the Examine*) function but 
this time a Value of zero for success means "no more entries in this 
directory" rather than "an error has occurred." By the way, while I'm 
on the subject let me say that if you are a serious programmer, or just 
an investigative one, you can discover why an AmigaDOS function has 
failed calling the loErrf ) function: 

error • ioErrO; 

The include file librancs/dos.h contains a complete list of the errors 
that you can encounter. 

AmigaDOS can also perform operations usually accessed from 
the CLI like rename a file: 
success > Rename ("oldname-, "nevname"); 



succese • Execute ("ccmand", input, output); 

where command is a string Just like the one you'd type from the CU, 
i.e "Dir dfl: opl a", while input and output specify how to redirect the 
standard input and standard output if there is no redirection in the 
command string. A value of zero for both parameters tells AmigaDOS 
to use the same standard input and output of the process that calls the 
function, usually the CLI A word of warning here: if your program is 
intended to run only from the CLI, it's okay to use zero for both input 
and output. If your program could be started also from the Workbench 
and uses the Executed function to run any other program in the 
background, you must provide at least a way to redirect the standard 
output: 

output « (*>en(-RAH:dummyfile. K>DE_HEHFIL8 ) j 
auccess ■ Execute ("Run HyProgram", 0, output); 
... your code here, then when it's time to exit... 

Close(output); 

Nonetheless, don't forget that the Execute!) function has two mam 
restrictions: the Run command must be present in vour C directory 
and the command that you want to execute must be either in the 
current or in the C directory. 

If you take a closer look at listing 2 you can see that each time we 
find a file with the archive bit not set, first we build a string like "Copy 
filename TO pathname CLONE" and then we call the ExecuteO 
function to copy it from the source to the destination directory. Of 
course we could use a series of Readj) and Writef) to copy it by 
ourselves but then the information about the date and protection bits 
would get lost. Unfortunately, since the Copy command must be 
loaded for each file, this might result in a somewhat slower operation, 
especially if there are a lot of files to back-up Nevertheless, if you're 
running AmigaDOS 1 .3 or higher, at the beginning of your working 
■cation you can make the Copy command resident by typing: 

Resident SYS:C/Copy add 
and everything will be |ust fine 

An in-depth discussion about the inner workings of AmigaDOS 
was far beyond the scope of this article and in fact I've barely scratched 
the surface. If you are a novice programmer and you're willing to leam 
more, a book that's definitely a must buy is SYBEX' "Programmer's 
Guide To The Amiga" by Robert A. Peck, a too soon passed away 
fellow who did a great job for the Amiga community. Needless to say, 
his work was and still remains valuable today. 



LISTING 1 



delete a file. 

success ■ DeleteCfil 



)J 



proti-ct a file: 

success ■ SetProtectloni-filename", maakvalue); 

create a directory. 

lock - CreaterDirCdimame"); 

e\ en establish a filenote 

success = SetCoanentCfilenaae". "comment"); 

However, the most powerful is certainly the Execute!) function 
that works exactly like its CLI counterpart: 



.key from/a, to/a; don't remove Iron herein 

This is a simple script to back-up the most recant files, 
hence the TODAY option in the LIST command, from a source 
directory to a destination directory. Pat this file in 
your S: directory and name it as you prefer. Osage is: 

execute scriptname sourcedir deetdir 

If you're using a shell like the one supplied with 
Workbench 1.3 instead of the old CLI, you can set itf 
script-bit to tell AmigaDOS that this one ia a script: 

protect scriptname *s 
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;And when you need a back-up just type: 
) Bcriptname sourcedir destdir 



.-Please change all references from RAH: to VDO:. RAD: or 
.-whatever the RAM-DISK you're using... 

IF NOT exists RAM:T 

KAREDIR RAM:T 
BNDIP 

;Don't break the following line! 

LIST > RAM:T/Temp <fron> LFORXAT^-Copy %s\s TO <to> CLONE' 
FILES SINCE TODAY 



struct FilelnfoBlock *fib; 
BOOL all, quiet; 

void string to lower (char • ); 

void output (char *); 

void cleanup(char *, lot); 

long fllecopylBPTR. char •. SHORT) ; 

int aaindnt argc. char •argv[)f 

( 

long success; 



/• Check args: source directory and destination 
directory 

are mandatory. That is. argc should be at least 

•qui 

to 3 V 



Echo "Please wait, sacking a back-up..." 
Execute RAH:T/Temp 
Delete fUM:T/TaBp 
Echo -Donel- 



LIST1NG 2 



if (argc < 3) 

cleanup (-Usage is: Backup From To [ALL] 
[QUIET] \n\n", 

RETURN FAIL) ; 
/* Okay, are there any options in the command line? If 
so, first convert then to lower case, then check 
then 

out •/ 

ail - quiet = PALSE; 



backup. c 



If you're using the Lattice/SAS compiler you can ccespile 
and 

link this code just typing: 
LC -b -r -v -Lcdn Backup 



Usage is i 

Backup From TO [ALL] {QUIET] 



if (argc > 31 



{ 



string_to_lower(argv[3]); 
string to_lower(argvt4]); 

if ((strcmp(argv[3]. "all") « 0) II 
(strcmp(argv[4], •■IX") « 0)) 
all ■ TRUE; 
if Hatrasp(argv[3]. "quiet") » 0) II 
(strcmp(argv[4], "quiet") =■ 0)) 
quiet « TRUE; 



'/ 



•include <stdio.n> 

•include <ctype.h> 

•include <string.h> 

•include <proto/dos.h> 

■include <exec /memory. h> 

•define COT_0P_HEM0RY 

•define EXAMINE, FAILURE 

•define createdir. failure 

•define kewlock failure 

•define COPY.PAILDRR 



-1 
-2 
-3 
-4 
-5 



/• A few global variables •/ 

BPTR sourcelock. oldsourcelock. destlock; 



if (all mm PALSE fit quiet mm FALSE) 

cleanupCOptions must be ALL and/or QUIBT\n\n\ 
RETURN_PAIL> ; 



1 



/' Get a lock to the source directory and. if possible, 
make the source directory the current directory. 
P.S. Locking a file or a directory it's the quickest 
way to find out if such a file or directory exist! 



sourcelock > Lock(argv[l], ACCESS READ) ,- 
if (sourcelock - HULL) 

cleanup! -Can't find SourceDir!\n-, RETURN^ FAI L) ; 
oldsourcelock ■ CurrentDir(sourcelock) ; 
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/' So far so good, now let's allocate enough Moory for 
a FilelnfoBlock structure. A FilelnfoBlock structure 
holds a lot of useful informations about a directory 
or a file and Is listed in the include file 
libraries/dos.h V 

fib • (struct FilelnfoBlock •lAllocHem 

lalzeof (struct FilelnfoBlock) , HEMP CLEAR) ; 
if (fib » NOLL) 

cleanupCOut of memory? !?\n". RETURN_FAIL); 



/• Okay, now we can use the Examined function to fill 
the PilelnfoBlock with the information about the 
source directory •/ 



/• This one is really trivial: just converts a string to 
lower case... */ 

void Btring_to.lower(cbar 'string) 
{ 
while('string) 

{ 
•string . tolowert 'string); string.*; 

1 

) 
/' And what about this one instead of printfo? He are 
Just 

printing strings, after all... */ 



success = Exaninetsourcelock. fib); 
if (success m 0) 

returnCCan't examine SourceDir!\n", RETURN.FAIL) ; 

/• Walt a minute! Is this really a directory? We better 
check it out... Within the PilelnfoBlock structure 
there's an item called fib_DirEntryType: if it is 
lesser than then we've locked a file! •/ 



void output (char 'string) 



I 



Write (Output O, string, strlen(string)); 



I 



if (fib -> f ib DirBntryType < 0) 

cleanupCSourceDir is not really a directory! \n", 
RETURN FAIL); 



/• Okay, before we fall int the main loop, let's do the 
same for the destination directory ■/ 

destlock = Lock(argv[2], ACCESS JtEAD) ; 
if (destlock >= NOLL) 

cleanupCCan't find DestDir!\n", RETURN.FAIL); 

success = Examlne(destlock, fib); 
if (success *3 0) 

returnCCan't examine DestDir!\n", RETURN FAIL); 



I* This one is called by mainO when an error has occured 
or when execution has been completed. V 

void cleanuptchar 'string, int error) 

Write (Output O, string, itrlenlstring)); 

If (destlock !- NULL] 
UDLocktdestlock); 

if loldaourcelock I- NOLI.) 

oldsourcelock ■ CurrentDlr(oldsourcelock); 

if (sourcelock !■ NULL) 
Unlock (sourcelock) ; 



if (fib -> fib DitEr.tryType < 0) 

cleanup ("DestDir is not a directory! \n", 
RETURN FAIL); 



/• Lucky guys!!! These really ARE directories... How I 
guess it's time to enter the main loop... •/ 

success • fllecopyfsourcelock, argv[21, 0); 



if (fib) 

FreeHemlfib, sizeof (struct FilelnfoBlock) ); 

exit I error); 
I 



if (success < 0) 

cleanupCWARNING: Back-up might be incomplete !\n\n", 
RETURN. FAIL); 
else 

cleanup("Done.\n\n", RETURN _0K); 
) 



/• This is the big one! This routine recursively calls 
itself until there are no more nested directories to 
examine. A few words about recursion?!? 
(...Deep breath...) 

When a function calls itself, new local variables and 
parameters are allocated on the stack and the function 
is re-executed from the start with these new variables. 
Once each recursive call returns, the old local 
variables and parameters are restored from the stack. 
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sz 



call 



execution can resume frcm the point of the function 
I 

inside the function. 
(Pfaeeeewwwwv! ! ! ) •/ 



long filecopy(BPTR lock, char -destdir, SHOOT dirlevel) 
1 
struct FilelnfoBlock •■; 
in-, size; 
long success; 
char 'target ■ NULL; 
char 'coanand « NULL; 
BPTR targetlock, dusBylock. newlcck; 
register SHORT j; 



site ■ sizeof (struct FilelnfoBlock); 

m ■ {struct FilelnfoBlock •)AllocMe»(slze, HEXF CLEAR); 
if (■ ■■ NULL) 

return (OUT_OF_MEKJRY> ; 

success ■ Bxamine(lock. m); 
if (success >■ 0) 

return { EXAHINE_FAILIJRE ); 



/• Now we can use the BxHextO function to examine 
all the entries within the saae directory. 
When BxNextO returns a we know there are no sere 
entries to examine... */ 

while! (BxHextdock, ■) > !■ 0) 
I 
if (m -> fib„DirEntryType > 0) /■ Directory? •/ 
{ 
if (all m FALSE) /■ Skip nested directories? 

( 

if (quiet « FALSE) 
< 
/• Tell about the directory being skipped 



• 



output (ta -> fib_FileHas*[Q])j 
output)" fdir)..[skipped]\n-); 
) 
continue; /• and juap to the next entry •/ 



) 



else /• Take into account nested directories '/ 

target - (char *)AllocMea(256, NEMF CLEAR) ; 
if (target •> NULL) 



( 
FreeHeotB, size); 
returo(0UTOF_HE»RY) ; 
) 
strcpy(target, destdir); 



If (destdirlstrlen(destdir) - 1| !- ':') 

strcat (target, -/"); 
strcatltarget, fca -> fib.FileName[0] ) ; 

if (quiet « FALSE) 
t 
for (j - 0; j < dirlevel; ]♦♦) 

output!" "); 
outputlfca -> fib_FileName[0]); 
output!- Idir)")j 
> 

/* If the target directory doesn't exists 
then we MUST create itl */ 

targetlock ■ Lock(target, ACCESS_READ) ; 
if (targetlock - NULL) 
{ 

If (Quiet ■> FALSE) 
output!-. .'); 
dumnylock « CreateDlr(target); 
if (duanylock »• NULL) 
1 
if {quiet « FALSE) 

output ("Hot created !\n"); 
FreeJiea! target, 256); 
Fre«Mem(m, size); 
return(CREATEDIR„FAILURE) ; 
) 
if (quiet -. FALSE) 

output ( - [created] \n"} ; 
UnLock ( dussiylock ) ; 

) 

t* Otherwise we can continue... •/ 

else 

< 







The remaining code for 
Listing Two can be found on 
the AC'S TECH Disk along with 

all other files 
necessary for this program. 



Please write to: 

Werther Pirani 

c/o AC'S TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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Programming The Amiga's 
GUI* in C 



•Graphical User Interface 

by Paul CasUm^uau 



This article is pari of a regular series designed to help you take advantage of many of the 
custom features of your Amiga using the C programming language. In this issue you will 
find: 

A discussion of the Amiga's internal message system and how it con be used to 
control your program's operation from the mouse or keyboard. 

A discussion of the Amiga's font system. 

New functions added to the programming shell that we have developed together 
over the course of the last few issues. 

A correction to last issue s article, having to do with how memory is declared when 
using Intuition's DrawBorderO function. 

An explanation of the Line^Anim program from earlier issues, which uses Intuition's 
DrawBorderO function to create smooth animation. This issue it has been en- 
hanced by using the Amiga's disk-based fonts. 



By now you are beginning to develop .1 flavor for what it's 
like programming the Amiga's GUI. If I had to as succinctly as 
possible describe thai experience. I would probably say that it 
was an exercise in data structures. That is to say. programming 
the Amiga is largely a matter of constructing certain data struc- 
tures, connecting them together in some required way, and then 
calling various system routines that use them to accomplish a 
desiicd effect As a result, your programming ability in this 
environment is dependent not only on vour proficiency InC . bill 
also on your familiarity with the wide variety of data structures 
and functions that make up the Amiga's run time libraries. And 
although C is oftentimes referred to as a transportable, system- 
independent language, what we are doing with it here is not 
transportable at all. 

PROGRAMMING SHELL, SHELL.C 

Due to space limitations in this issue, copies of the pro- 
gramming shell could not be placed within each example direc- 
tory. If you want to modify and re-compile any examples, vou 
must first copy Shell.o and Shell.h from the Shell directory into 
the example directory. You can then either enter LMK on the 
AmigaDOS command line, or double click the Build icon on the 



Workbench. Since the shell is used at the object code level, it is not 
necessary to copy its source code. Shell.c, into example 
directories^To Stat) your own new projects using the program- 
ming shell, you must first create a project directory, as required 
by SAS/C. If vou like to use icons, simply doubleclick SAS/C's 
s.w setup icon (in the LC: logical device). It will prompt you for 
a directory name for your nevi project If you prefer operating 
from the command line, use the AmigaDOS, MakDir command. 
Next copy into that directory Shell.o, Shell.h, Imkfile. and 
UserJ'rogram.c. Do not copy Shell.c. It is not required. 
User_Program.cisaconvenientgeneru starting place for all your 
programs. For more information on the practical operational 
aspects of SAS/C, refer to earlier issues ol this article series. 

This programming shell is a convenient environment in 
which toconduct programming experimentson your Amiga It is 
not a competitive, minimum size, development environment. 
Observant readers will notice that Shell.c is a rather targe file 
about 2000 lines. However, because you use its pre-compiled 
version, Shell o, it does not affect the compile time of your 
projects It you modify the ShelLc source code itself, and you want 
to re-compile it. use the make f lie 01 lied LMK_Shcll.c, also located 
within the Shell director] 
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GOTTA 

GETTA S 
GUIDE! 



Looking for a specific product for 
your Amiga but you don't know who 
makes it? Want a complete listing of 
all the Fred Fish software available? 
Just looking for a handy reference 
guide that's packed with all the best 
Amiga software and hardware on the 
market today? 

If so, you need AC's GUIDE to the 
Commodore Amiga. Each GUIDE is 
filled with the latest up-to-date- 
information on products and services 
available for the Amiga. It lists public 
domain software, users' groups, 
vendors, and dealers. You won't find 
anything like it on the planet. And 
you can get it only from the people 
who bring you the best monthly 
resource for the Amiga, Amazing 
Computing. 

So to get all this wonderful 
information, call 1-800-345-3360 today 
and talk to a friendly Customer 
Service Representitive about getting 
your GUIDE. Or, stop by your local 
dealer and demand your copy of the 
latest AC's GUIDE to the Commodore 
Amiga. 
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MOVING? 




SUBSCRIPTION PROBLEMS? 



Please don't forget to let us know. 
If you are having a problem with 
your subscription or if you are 
planning to move, please write to: 



Amazing Computing Subscription Questions 
PiM Publications, Inc. 

P.O. Box 869 
FallRiver, MA 02722 



J 



Please remember, we cannot mail your 
magazine if we do not know where you are. 



lease oilow four to six weeks 'or pf ocesstng 
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ACs TECH Disk 

Volume 2, Number 3 



A few notes before you dive into the disk! 



You need a working knowledge of the AmigaDOS CLI a. most of the files on (he 
ACs TECH disk are only accessible from the CLI. 

In order 10 fii as much information as possible on the ACs TECH Disk, we archived 
man) of (he files, using the freely a"disiri tunable archive utility 'lharc' (which is 
provided in ihe C: directory), lharc archive files have the filename extension .1/Ji 

To unarchiu* .1 fOepjaWl, type Hum 
For help with lharc. type lharc ? 

Also, files with 'la I ' u CM can tv unanlmcJ from the WorkBench by double-clicking the icon, and supplying a path. 




We pnde ou*wives m the quoUtv of our print 
ond mognetic medta publications However. In 
the highly unlkely event of a faulty or dom 
aged disk, please return the dfek to PiM 
■ uU ^-jtions. Inc for a free replocement 
"'case return the desk to 

AC « tECH 

Oik l^ftntnr*-"""' 

P.O.Bo«2ldU 

Fatin . — 



Be Sure to 
Make a 
Backup! 



J Out H'Oit «.»».»( ...■ . ._ jnalumcol 

in* tn.71.1m. , n ihr ai ■ 1 1 1 11 i>.t •< mfrm ihc 
miei m ui* camem. c.prvi«l]> *hcn »«n( » ipctimcnu! 
pmpumih* mitunr hwtiwi -di _ .,-.. It* wir 

llJTalltl iM thf l(Mlkl) atl prftamunii u( Ihc ->'l-#rt c-l 

1 1 )l DknV 11 itwwd b> ihc punhawi ISM 

IVNk-jIi>-«i. Inc. thru tlnlnrumi m thru irUik'i -ill 

rnfl hr luMr fi« m- dimi inlirtit. m i iwmpwinl 

■jwiufo iruahiaf Inm ihr m« numvi.t i' 
.nuXACiTTCIIRiii IIh.jftrcnwnlu>M«nil) 

in ill jr»frir*». il iruii 
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i wo more things First, starting In this issue, ! am compiling 
the Shell.o module, and .ill example programs, using SAS/C's 
absolute addressing option. -bO. Example si/es are getting large 
enough thai \ou will start to have trouble linking them it vou 
continue to use the relative addressing mode, -bl Second, be 
warned that you nm*t Increase your system slack size over the 
Amiga's default 4000 bytes. I use 30.000 bytes on my system. For 
all the examples in this article 8000 bytes will work fine. 

Now, let's get on with this issue's article. 

INPUT/OUTPUT PROGRAMMING 

If you design a program to use the A migaDOS command line 
to interact with the user, you can use the normal. Standard C 
scanfO function to make it respond to keyboard entries But such 
programs are limited to simple text style operations, and are 
unable to lake advantage of the real graphic power of the Amiga 
loaccomplish keyboard input within the realms of Intuition, you 
must use a different approach, and as you should be growing to 
expect, there are several ways of doing it. Some are high level, 
requiring relatively little knowledge of the internal workings ol 
the machine. Others are 
lower level and require 
more \aturally mv first 
introduction to this will 
be at a level that requires 
tin- least amount of effort 
on your part. Thus you 
will be able to enjoy the 
benefits of programming 
your Amiga in C as 
quickly as possible 



company's trunk lines Messages generated by different periph- 
erals and programs travel back and forth along this common 
1'auhtv, each satisfying perhapsadifferont requirement. I he term 
ir,--s,age port" is used to describe the equivalent of the telephone 
company's central dialing office. These are locations where dif- 
ferent programs and peripherals are given access to the message 
Stream For vour program to receive mouse or keyboard informa- 
tion, it must somehow get connected to a message port, where it 
can be given access to the message stream along which such 
information travels. Note thai although there may be a lot of 
activity on a computer's message stream at any one time. \ our 
program should not respond until somewhere a message is 
generated just for it 

THE AMIGA'S INTERNAL MESSAGE STREAM 

The easiest way to connect your program to the Amiga's 
message stream is to ask Intuition todo it for you, and you can do 
that during your program's initialization phase by assigning a 

special value to one of the members in its \ewWindow structure 
Recall that it is within this \ewVVindcm structure thai vou enter 
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TELEPHONES AND 

COMPUTERS 

COMPARED 

Think for a moment 
about your telephone 
and how through a single 
line connected to your 
home you are able to 
communicate with mil- 
lions of different people 
around the world. Won- 
derful Isn't it? All that is 
possible because your 
one telephone line is 

physically connected to a local, central dialing office (near your 
home) through which you can be switched or connected to a 
variety of high capacilv. long distance circuits, along which your 
voice travels with thousands of others until it ultimately gets 
intercepted by another central dialing office situated close to the 
person you are calling. These high capacity circuits are called 
trunk lines. Thus all telephones are interconnected, not directly, 
but through a shared, communications system. Note also that 
although there may be a lot of activity on the telephone s\ stem al 
any one tunc, vour phone doesn't ring until someone, some- 
where, generates a message sore it i ( ally for you Computers have 
similar communication systems that provide message handling 
between their various peripherals and programs. The term "mes- 
sage stream" is used to describe the equivalent of the telephone 



0pen_Libs< ) 



0pen_Hv_Screen<) 



-t»| 0pen_8tank_Hindow<) 



a description of the window you want Intuition to generate for 
your program. One of its members is called IDCMPFlagS, and its 
purpose is to tell Intuition what kind of communication vou want 
your program to have with the rest of the system. Intuition 
responds by setting up a message port which connects your 
program to the Amiga's message stream. That rather cryptic 
name, IDCMP, is an acronym for "Intuition Direct Communica- 
tions \h-ssage Port." the actual values thai you assign 10 
IDCMPFlagsare macros, which have been conveniently defined 
for you in the <intuition/intuition.h> header file I or example, to 
have your program receive messages from the mouse you assign 
the macro MOUSE BUTTONS. 
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ADDING IDCMP TO Open_ShellO 

In our programming shell, the NewWindow structure is 
hidden away within the Open. Blank_Window() function, a pri- 
vate function within Shell.c. Such concealing of the details of 
creating windows is a desirable way to design programs. It helps 
us to belter come to grips with their complexity. This is an 
example of the formal, computer science principle called "Infor- 
mation hiding," remember? But now we need to gain access to 
some of that hidden detail, so lei's go in thereand see how we can 
do that. 

In figure #1 1 show the hierarchical structure within the part 
of the shell that gives us our graphic drawing surface: 

In article 3 of this series the prototype definition of 
Open_Blank_Windo\v() was: 

BOOL Open_Blank_Window(struct Screen Tny_screen, 
ULONG my _i dorp, 
struct Window * <"my_window) , 
struct RastPort "("my_rp)J 

As you can see, I have already designed this function to 
accept an argument for assignment to the IDCMPFIags member 
of the NewWindow structure. Now isn't that convenient. Within 
the body of that function the parameter "my_idcmp" gets as- 
signed to the IDCMPFIags member of the window_description, 
NewWindow structure. So to set up communications between 
yoiirprcgr.im.ind (he mouse all you need to do is pass the macro 
MOUSEBUTTONS to the OpenjBlank_Window() function. 

Moving up the hierarchical tree of Shell.c (from article «3), 
we look within the Open_Shell(> function and notice the following 
call: 

Open_BUnk_Windowfmy_screen, NULL, my_window, 
my_rp> 

where a NULL is passed as the IDCMP argument. A NULL 
assigned to the IDCMPFIags member of the NewWindow 
structure tells Intuition not to set up a communication connection 
between the program and the system's message stream. In those 
early examples I wanted to keep things simple. In order to set up 
such communications now wecould simply change that NULL to 
MOUSEBUTTONS, but that would not be correct. You see, the 
above call is within our Shell.c module, which we want to pre- 
compile and use "as is" in many different programming ex- 
amples. Adding MOUSEBUTTONS at that point would force all 
our programs to use exactly the same IDCMPFIags definition 
Instead we want to be able to specify MOUSEBUTTONS, and 
other possible macros, from the main program, when we call 
Open_Shell(>. 

Here is the prototype definition of Open_Shell{) as it stood 
last issue: 

BOOL Open_Shell (struct Screen " (*my_screen) , 
struct Viewport *( , my_svp), 
struct Window • < *ny_window) , 
STRPTR resolution) 

Too bad, I forgot to design that function to pass a value for the 
IDCMP message system. Well, we'll just have to add a new 



parameter to do that right now. 

It you look at thisarticle's source code for Shell.c vou will see 
the new prototype definition. 

BOOL Open_Shell(struct Screen 
•Cmy_screen> , 

struct ViewPort 'l"my_svp). 
struct Window • ( "my_window» , 
STRPTR resolution, 
ULOW3 ny_idcmp) ,- 

as well as a modified Open_Shell() function which passes 
your IDCMP request on toOpen_Blank_ Window ((.Now vou can 
specify a particular IDCMP macrodirectly from mainf), in the call 
toOpen_Shell().Tocreatea window that will receive mouse click 
messages you make the following call: 

Open_Shell (&my_screen, &my_svp, &my_window, 
&ny_rp, "LACEHIGH16 - . MOUSEBUTTONS); 

PROCRAM MAINTENANCE 

I walked you slowly through the above modification process 
in order to makea point, that in a well structured, well documented 
program, it is easy to find the correct spot to add a new feature. 
Note, however, that the compiled code, Shell.o, of this article will 
not work with examples from previous issues because the number 
of parameters in the Open_Shell() function is now different. But 
because wi- have been diligent enough to use tin- new ANSI 
prototype definitions in all our code, the compiler should warn us 
if we ever accidentally try to compile an example with a wrong 
version of the programming shell.. 

READING AND REPLYING TO MESSAGES 

Having informed Intuition what kind of messages we want 
our program to receive, we must now consider how to read them 
ome they arrive at its message port. Your first question is surely, 
"Where is that message port?" Its address is stored in the Window 
structure that Intuition created for you when your program 
invoked Intuition's OpenWindowf) function. It is in a member 
called UserPort. In our programming shell we have been using 
the variable name "my .window" to point to our program's 
Window structure, so the address of its message port is 
"my_window->UserPort." Note that the UserPort itself isa struc- 
ture of type "struct MsgPort," defined in <exec/ports.h>. 

When messages arrive for your program. Intuition saves 
them in special buffers that it allocates dynamically, and it hangs 
on to them until you get a chance to read and process them. The 
messages themselves are stored according to a C structure called 
IntuiMessage, which is defined in the <intuition/intuition.h> 
header file. For the moment let's not worry about the details of 
that structure. Just be aware that it exists and that your messages 
are being stored dynamically, somewhere in memory, according 
to it. As more messages arrive, Intuition piles them up, dynami- 
cally allocating more memory space to hold them. 

To read a message, you must invoke the GetMsgf ) function, 
using as an argument the address of your program's message 
port, in this case "my_window->UserPort.". The GetMsgf) 
function returns the address of the first in a possible list of 
messages waiting to be processed by your program. Since mes- 
sages are stored according to an IntuiMessage structure, we 
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assign Uw address returned by GetMsgO ton pointer of that type, 
like so 



•■ossage nv_^essage = 
Message ' window- 

! 

It there i> no message In the port. GetMsgO returns a MULL 

Reading a message does not satisfy Intuition that vou are 
finished with it. Intuition continues to hold on to messages until 
you specifically give it permission to do otherwise, and you do 
that by formally replying to them. Replying to a message con- 
firms to Intuition that its contents are no longer needed and that 
it is OK to deallocate its temporary buffer. You rep] v toa message 
by invoking the ReplyMsgQ function, using .is .in argument the 
address of the message you are finished with, like so: 






• rrry__messagel ; 



WHEN DO MESSAGES ARRIVE? 

I here are two methods for checking if and when messages 
arrive at a window s message port I lu-y .ire called waiting and 
polling. In the waiting method, your program pauses (stops 
normal execution) until a message arrives. This method is similar 

to using BJ1 l\l'l I Statemenl In BASIC, where the program 
temporarily suspends all operations in anticipation of some user 
response. It is used whenever your program needs something 
critical for its operation, something without which it cannot 
proceed In contrast, the polling method does not suspend your 
program's operation. Normal processing continues, while at the 
same time regularly checking the message port to see it any 
messages arrive, this method is similar to the KEY INPUT 
statement of True BASIC, or the IV latement of 

AmigaBASIC. It is used in simulation and animation programs 
where processing must not be interrupted, but where it is also 
necessar) to respond to user input. The above example, 
I Irsl Mouse.C, used this polling method to check for a mouse 
click by continually looping around a GetMsgO instruction. The 
example did not perform any other processing while it was 



You can ask your program to receive both mouse and keyboard 

messages, by using C's bitwise inclusive OR operator between 

the MOUSEBUTTONS and VANILLAKEY macros. 



Thecast to (struct Message*), rather man (struct mtuiMessage 
•), is needed because mat is the type defined for the argument of 

the ReplyMsgO function in its prototvpedefimtion, in the <proto/ 
exech> header file. Struct Message is a more general structure 
used when you define your own message ports, as opposed to 
using ones generated for you by Intuition. But. of course, that s .1 
subject for a future article 

The two functions, GetMsgO and ReplyMsgO are always 
used together. If you do not reply to messages, their butters will 
not be de-allocated and your program will eat away menmi j as 
more and more of them arrive. Below I show a simple example of 
a program that reads a port until a message arrives The "do loop" 
executes until the pointer "my .message" receives a legal address 
for a message. The example does not process the message; II 
Simply acknowledges its receipt by replying immediately to it. 

* uiMessage •nty_jnessage 
do 



ny_pessaae = 
"IGetMsglrny * i - 
I while fry _r**uge ■ 



t uiMessage 



• Imyjnessagel ; 



Vou will find the above example <m the magazine disk, in the 
drawer called First_Mouse. In that program the macro 
MOUSEBUTTONS is sent to the Open.ShellO function. Thus, 
pressing the left mouse button anywhere in the window causes 
execution to exit the "do loop" and the program to terminate. 



polling, but of course it could have. 1 ater in this article, you will 
see how the I ine Anim program uses polling to test for user 
response, while at the same time processing a complex graphic 
animation 

WAITING FOR MESSAGES 

To temporarily suspend your program's operation and have 
it wait for a message to arrive, vou invoke the WaitO tunction It 
takes a single argument, called an input mask, which allows the 
system to signal your program when a message arrives. 

A mask is a number that is generally used to test for values 
at (ertain bit position-, in binary number-. I m example, totind out 
if bit 3 of a binary number is set (equal to one) vou could use C's 
bitwise AND operator with a mask, like this: 

■ • 

• 7654321C :;• */ 

munbei to test •/ 
mask • ask 

■ ■ ■ 
■ 

I he "A;" character ;■•( 8 bitwise AN!) operator. The "«"is 
C's bitwise left shift operator. Refer to page is ol The C Program- 
ming Language, Second Edition, by Kemighan & Ritchie, Prentice 
Hall 1988, if you need to brush up on C's bitwise operators. 
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The valueof(d&mask) is zero for all values of d except those 

whose3rd bit issetibitsarenumberiH) from theright start e 
OkThus theabovccode tests for the presence of the third bit in any 
number d. I used C's bitwise left shift operator to construct the 
mask, rather than the equivalent decimal number 8, because it 
identifies explicitly the bit position thai the mask is testing for. 
Although writing (d &S) would workexactl) the same, someone 
leading the code, and trying to figure out how ii worked, would 

have to nxall that the number S represented hit position 3. 

Well, that's what mask-, are used for, and although you do 
not need to know the exact details of how the operating system 
uses the particular mask that you pass as an argument to the 
Wait() function, you do need to know how to construct it. You do 
that in the same way as I constructed the above mask, b\ using C's 
bitwise left shift operator on the number 1. But how much should 
you shift it? That magic value is conveniently stored in your 
program's UserPort, in a member called mp_SigBit (message port 
signal bit). The mp_SigBit member of vour program's UserPort 
contains a bit position that the system must use in order to Signal 
your program when a message arrive* From that value vou 
construct the mask, like so: 



UserPort. One of these functions will use the wait method, 
putting program execution on stand-by until a message arrives. 
This function will be useful in many of our examples lor grace- 
fully terminating program operation. We can simply display a 
prompt like, "... press any key to quit .. .", or ".. click let! mouse 
button toquit ...", and then wait for the user to respond. The other 
function will use the polling method, and it will be useful in 
animations, where processing must proceed while at the same 
time responding to user entries. Neither dI these functions » ill 

process the received messages in any way. I am not interested at 
this point in what these messages mean, or even where the) come 
from. I just want to know when ihcv arrive, and of course I wan) 
to properly reply to them. 

SleepO FUNCTION: 

Below is my completed design for the first function, which 
USes the wait method of event enquiry: 

VOID Sleeptstruct Window ■ 
i 

'■ ssage 'iny_messa 



mask ■ 1 « rny_window->UserPoti 

Vou voursflt need not know tin- bit position of that mask, but 
ofcourse you can find out, it vou want to, by placing lewprintf() 
instructions in any one of my examples. Doing so will help 
solidify your understanding of what is going on here. Remember. 
how e% er, that printfl ) instructions display text in the Amiga! K >S 
window from which your program was launched, not in its 
graphic window. 1 heretore. it vou want to add such scaffolding 
to vour program, you should launch it from the AmigaDOS 
command line, as opposed to double-clicking its icon from the 
Workbench. 

N ou call the WaitO function with the above mask, like this: 

mask) ; 

1 he result is that execution of your program halts— it SOI t ol 
enters a state ui suspended animation — until a message is received 
at its message port Waiting is the preferred method of accepting 

keyboard or mouse response in a multitasking s\ stem because it 

allows the operating system to allocate more system resources to 
other tasks that mav be running at the same time >, ou Will find an 
exampleof the wait method ot reading messages on the iiia^.i/ me 
disk, in the drawer called Waiting. 

INPUT FROM THE KEYBOARD 

To have your program recei\ e messages from the keyboard. 
you can use the IDCMP macro called WWII I AKI V. It causes 
your program to receive ASCII codes corresponding to whatc\ ei 
letters the user presses on the keyboard. You can also ask for your 
program to receive both mouse and keyboard messages,!)) using 
Csbitwise inclusiveORoperator between the MOUSEBUTTON5 

and VANII I AKI V macros I he example in the directory called 
Ftrst_KeyboardO does that 

STRUCTURED EVENT ENQUIRY 

I would now like to design two new functions, to make it 
easier lor us to tind out if messages ex ist.it any lime in a program s 



mask = 1 « my_window->U£' 






while (rry_messag 
" ) GetMsg t ny_wi no* * 
ReplyMsg ( [at 



1 if nic t 



liKe: 



imy_rnessagel ; 



i 

This function accepts as an argument the address of the 
Window structure of your program. It constructs the required 
input mask, and then calls the WaitO (unction. At thai point 
program execution stops until the user performs some required 
response Upon being revived,the function executes a while- 
loop" to purge the message port of all other messages, in the event 
that more than one was received. 

UserPort_message<! FUNCTION: 

Below is my completed design for the second function, 
which uses the polling method of event enquiry: 

BOOL User Port_mes sage (struct Window 'my window! 
I 

• uiMessage "rry_niessage - NULL; 
my_roessa.:> -ssage 

• IGetMsg <my_winbA .. 

"/-message == NULLI 
-urntFAI, 
else 



ReplyMsg ((struct Message ■ 
while (my_message = (strui 
•> GetMsg (r 

Reply ■ 

return (TT- 

) 



mpQSrinH 1 
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This function also accepts as an argument the address of the 
Window structure of your program. It returns a TRUE or FALSE 
to report the presence or non-presence ni , i message in its User Port. 
If a message exists, the function immediately replies to it. and 
then purges the port of any additional messages that may have 
been received. 

The above two functions have been placed in Shell.c of this 
article. Program examples demonstrating their use are in the 
drawers called Polling and Sleeping. The polling example flashes 
a prompt on the screen, while simultaneously calling 
UserPort, message^). It does this by continually executing a "do 
loop" whose exit condition is: 

while! !UserPort_jne3sagetmy_window) ) 

which means, "loop while there is no UserPort message for 
my_window " 

In previous articles my examples would remain on screen for 
a fixed period of time, determined by the DclayO function. That 
was very crude. Now with IDCMP messages we can end our 
examples in a more professional manner. 

There is a lot more to learn about IDCMP messages. I have 
not even mentioned what information they contain, nor how 
your programs can go about processing them. I will return to 
lUCMP's again, in a future article. 

FONTS 

The Amiga has a standard set of fonts that can be used to 
enhance any program, allowing vou to give your work a profes- 
sional appearance. Mere are the standard fonts available on all 

Amiga's: 



Ve.-ionl - 


Version 2.04 


Courier 


CGTimes 


Diamond 


GTriumv irate 


Emerald 


Courier 


Garnet 


Diamond 


Helvetica 


Emerald 


Opal 


Garnet 


Ruby 


Helvetica 


Sapphire 


LetterGothic 


Times 


Opal 


Topaz 


Ruby 


Sapphire 


Times 




1 opaz 



On a version 1 .3 Amiga the Courier, Helvetica, and Times fonts 
are located on the Extras disk. Each font styles comes in more than 
one size, adding up toa total of 32 sizes in lOstyles lor version 1 3. 
For information on how to configure a floppy system such that all 
fonts are available, refer to "System Configuration Tips for SAS/ 
C" Volume 1 , Number 3 of AC's TECH/AMIGA. Topaz is the font 
style contained in the Amiga's KickStart ROM, and it is usually- 
referred to as the Amiga's default font. It comes in two sizes, 
selectableon a version 1 .3 system from the preferences screen. All 
other fonts are disk based. That is, their graphic data exists on 
disk. For some programs, like full-featured editors and word 
processors, it is important that they use whatever font the user has 
selected as a system default. 

But as a hobbyist you may not want to design that feature 
into your own programs, at least not for a while. Designing 
programs to work elegantly using different default fonts can be 
tedious. Chances are you will want to move quickly to more 
interesting programming exercises. Thus, a good practical ap- 
proach is to have your program ignore whatever font the user has 
selected as a system default, and to load instead whatever ones 
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TextFont 
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you decide it should use. liven if .ill you ever use is topaz. 80- 
column text, there is no real guarantee that your friends with 
whom you share your work will indeed select that same tont as 
a system defaull when they run your program, especially now 
with the new 2 operating system. To be sure that your program 
gets the font, or fonts, that it needs, it should explicitly pick them. 
I Ins does not mean that you no longer need to account for 
different sized fonts, bul by your making the decision of which 
ones to use, your program's design is greatly simplified. 

OPERATIONAL STEPS 

To use a particular font within vour program, you must use 
the following operational plan: 

1 -Declare a TextAttr structure in which you will store a descrip- 
tion of the font you wish to use. I like to call this the description 
structure. This is not the font itself, only a description of it. 

2 Declare a TextFont pointer that will eventually hold the 
address of the font you wish to use 1 his is not an instance of the 
font, but a pointer to one. It is usually initialized to Mil 

3 - Open the "diskfont. library" run-time library. Recall that the 
OpenJ.ihsO function ot our programming shell already does that 
for you. 

4 - Assign to each member of the description structure the 
characteristic of the font you want to use 

5 - Call the system function that makes the font available, either 
OpenFontO or OpcnDiskFontO. uMiig as K m argument the ad- 
dress of the description structure declared in step 1 . and assign 
the value returned by the function to the pointer declared in step 
2. Is this getting to sound familiar? 

6 - Test the value assigned in the font pointer to determine if it is 
indeed legally available. You will see either a legal address, 
representing a legitimate font that you can use, or a NULL, if for 
some reas,m the system could not make it available. 

7- Use the font pointer throughout your program to access its 
features and control it in different ways. 

8 - Close the font before your program terminates, allowing the 
sj stem to re-allocated whatever memor) it was using. 

IMPORTANT STRUCTURES 

There are two structures that are important when dealing 
with the Amiga's fonts. TextFont and TextAttr. TextFont is the 

most important of these It is within aTcxtFont structure that the 
OpenFontO function loads ,i font into memory, making it avail- 
able for use It contains the actual bit character data of a font. For 
your program to use a font there must exist, somewhere in 
memory, a TextFont structure representing it, and of course your 
program must have a pointer to that structure. The lext \tfr 
structure contains only a short description of a font. It is used in 
conjunction with the OpenFontO and OpenDiskFont() functions 
to load new fonts into memory, which is how you make them 
available. It is also used in conjunction with the IntuiText struc- 
ture, to specify different fonts when using Intuition's high level, 
text rendering PrintlTextf) function, as well as in conjunction 
with the Ask! ont() function, to identify the current font, should 
you ever need todo that. The templates for both the TextFont and 
the TextAttr structures are in the <graphics/text.h> header file. 

THE AMIGA'S ROM BASED FONT 

There are two sizes of topaz font stored in the KickStart 
K( At They are often referred to by the number of columns that 



thev can display on a high resolution screen; thus the names 

TOPAZ.EICHTY and TOI»AZ_S!XTY in the <in tuition/ 

preferences. h> header file. However, I will refer to them using 

names that reflect their pixel height, topa/8 forTOPAZ_EIGFTTY, 

and topazv for TOPAZ_SIXTY. 

To make a particular ROM-based font available to your 

program you must invoke the OpenFontO function It take- one 

argument, the address of a TextAttr structure containing its 

description. You should have no trouble identifying the points 

from theabove operational plan within the following code, which 
loads and uses topazS: 



scruc r desired_font;/* 

struct TextFont "topaz8 = NULL;, 



' 
plan 



snt 






TOPAZ_EIGHTY; 
desire: ■ FS_NORHAL; 

■ od_font . PF.DESIQJED I 

FPF_BCWF' l 

topazB = Oper.T -.- 1. T •■.•■•/• step I 

plan 
* 

/' step six of plan •/ 

ike corrective action . . . 



Ser.Font(iTv_rp. ■ • 
Hove(my_rp, 0, 10); 
Text(ny_rp, -Hello- 



step seven of plan •/ 



bi ; 



if(topazB) • step eight of plan ■/ 

CloseFont (topazB) ; 

The la Name member of the TextAttr structure is assigned a 
string consisting of the name of the font, a period, and then the 
word "font," all concatenated together. The ta YSize member is 
set to the vertical pixel size ot the font I used the convenient 

macro TOPAZ EIGHTY, from the <intuition preferencesJi> 
header file. The ta_Stvlc member is set to normal, meaning that 
the font has no special Style characteristics. hKo bold, italics, or 
underline. All the Amiga's standard fonts are stored as 
FS_NORMAL, although they can be algorithmically modified to 
crcateotherstvU-s— moreabout that in a future issue The ta Rags 
member is set to the font's location, in this cast- the Ktckst, u t 
ROM.Theother macro, FPF_I)FMt ,\l I ) issupposed to instruct 
the system to load a font that has exactly the characteristics you 
specify, although to tell you the truth I havenot been able to verify 
that it works as intended. Perhaps I have been ill-informed on its 
purpose. Can anyone out there help? 

The above code opens lopa/N for use in your program. If the 
user has already selected that font as the system default, the 
Openl onto function will return itsexisting address; that is, it will 
return the address of the Text I out structure already representing 
thai font in memory. Otherwise the font will be loaded into 
memory from the KickStart ROM. Vou should always \ erify that 
the address you receive from the OpenFontO function is legiti- 
mate, even for the ubiquitous topa/8. Opening fonts within your 
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programalso gives you a new responsibility. that ot , losing them 
before your program terminates. You close previously opened 
fonts by invoking the CloseFontO function. 

USING A FONT 

Opening.! tout places it in memory where it becomes available 
for use. but to actually use it, with the primitive I "e\t(| function. 
\ on have to tell the system to make it your program's current font. 

You do that with the SetFontf) function, like so: 

SetFonc (nr/_rp, topazB) ; 

In contrast, the higher level PrintlTextO methtnl of rendering text 
does not require the use of the SetFontf) function. It relies instead 
on a pointer to a TextAttr structure describing a previously 
loaded font. To render screens consisting <if text in more than one 
fonl you construct multiple IntuiTcxt structures, each one point- 
ing to its own font TextAttr structure and text. You then link these 
structures together using their NextlText members, and render 
them by invoking a single PrintlText() instruction. The line ani- 
mation program later in this article contains an example of this. 

POSITIONING TEXT 

On the magazine disk, in the ROM_Fonts drawer, you will 
find an example that opens, uses, and finally closes the twoKOM- 
based fonts. The example also uses a resolution independent 
technique for placing text on the screen. When using different 
fonts it becomes increasingly important to takeintoconsideration 
their different sizes and baseline positions. You can read that 
important information from your window's KastPort structure, 
in the TxHeight, TxWidth, and TxBaselme members. Notice how 
I center text on the screen in the ROM Fonts. c example: 

:'RPTH) £ont_t .' .• . " [-j.- ».:", 
.■_windov 
nl (STRPTR) fc 

.ne_posit ion; 
Move(my_rp. x, y); 
Text (my_rp, (ST!- : 
strlenUSTHPTRJft: 

The horizontal pixel position is calculated by using information 
stored on the system Ihem\ _window->Width is the pixel width 
of the screen. The my_rp->Tx Width is the pixel width of one 
character in the current font. The calculation subtracts the pixel 
length of the text from the width of the screen and divides by two. 
In the aboveexample the vertical position is kept in a variable 
called "Une_position". It is initialized using screen dimensions 
stored on the system: 

line_posicion = my_window 

and updated by incrementing it by the sum of the height of the 
font and a space ol two pixels. 



Y '- 



• 2 



The above text positioning technique has the advantage thai it is 
independent ol the resolution of the screen. Trv it out yourself. 



Change the resolution to LAC EH1GH2, and you will see that the 

text is still properly centered. 

DISK-BASED FONTS 

To make a disk based font available to your program vou 
must invoke the OpenDiskFonlO function. It works exactly like 
OpenFont(). It accepts as an argument the address of a TextAttr 
structure, and it returns to your program the address of the 
u'rrespondingTextFont structure that it loads into memory. 

struc- .. *dicunond20; 

stru ■ rant; 



desi. 



* 



DESIGNED 



nu ; 



desi red_f ont . t a_H . ,1 ; 
FPF_DISKFONT 

diamond20 Opt-: 

:iamond20 = * NULL); 
I 
. . -co: on... 



The ta„\ame member of the text attribute structure is con- 
structed in the same way as for our earlier topaz example. The 
name "diamond. font'' actually corresponds to a tile on your 
system disk, in the FONTS: directory. Thus you don't need to 
spend time flipping through documentation to find the correct 
name for a font, you just look on your disk using the following 
command; 

onts: 

You will see that for each ".tout "tile there exists a corresponding 
directory in which the font's bit data is stored. To find out what 
sizes ot diamond font are available, enter: 

imond 

You will see that the name of each "bit data file" is its actual size 
On the magazine disk, in the drawer Disk_Fonts, you will find an 
example that loads into memory and uses the two available sizes 
ot diamond tont. It usesa new function for positioning text on the 
screen. TextLength(). You sec. diamond is a proportional font. 
That is, its individual letters are not all the same width. In fact, that 
is the reason whv it looks so nice. But the problem is, the value 
stored on the svstem tor character width, my_rp->TxWidth. is 
now only .m average Using it to center text will give erroneous 

results The I extlenj;th( i Junction solves that problem by return- 
ing the exact pixel length of any string in the current font 



i20 1 ; 
y_rp, "H< 



S); 



h-xtl .ength requires three arguments: the KastPort pointer, the 
string whose pixel length you want to measure, and the character 
length of the String. I lere is oiw ot the text centering calculations 
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from Disk_Font.c: 

x b lmy_window->width - TextLe:igth(my_rp, 
line_one, strlen(line_onel ) )/2 

It is important that you understand these text centering calcula- 
tions. 

TOO MUCH DETAIL 

lfyouareataUlikeme,you are beginning to get overwhelmed 
by the large amount of detailed work that must be done in order 
to use a particular font. Shouldn't things be easier? Of course. 
Practically speaking, if you intend to make regular use of the 
Amiga's fonts, you should organize this entire operation into one. 
simplified, structured form. But of course here is where many 
programmers differ. Everyone has their own programming style. 
IX'spite that, I have designed into our programming shell a 
convenient way for you to use the Amiga's fonts. I hope you like 
it. And if you don't, I hope it at least gives you some constructive 
ideas on how to design your own. 

GLOBAL FONT POINTERS 

To allow you to conveniently use any font from any section 
of your program, I have decided to make their pointers global. 
Yes, I know it's dangerous to use global variables, but I promise 
to be good and document them well. Besides, my naming con- 
vention will make them easy to recognize. Each one will consist 
of the name of a font and its size concatenated together, as in 
sapphire!9, oremeraldl7. You will find such global font pointers 

decla red at the top of this issur's Shell ih k- r one for each Standard 
lont style and size. You will also see some corresponding TestAttr 

Structures, with names like t.i sapplurel9,and ta_emeraJdl7.AJJ 
these global variables are referenced again within the Shell. h 
header tile, as indeed they should be. Remember, it is in the 
Shell. h header file that your program picks up whatever global 
function and variable declarations it needs in order to use the 
Shell.o pre-compiled module. 

Load_Fonl(> FUNCTION 

I have designed this function to facilitate the loading of any 

font . It takes one argument, the name of the font you want to load, 
enclosed within quotes - like this: 

error = Load_Font ( -sapphirel9' ) ; 

The function uses the string argument to identify which font you 
want It then calls Intuition's OpenDiskiontl), using as an argu- 
ment the address of the desired font's global TextAttr structure. 
It also assigns the address relumed by OpenDiskFont() to the 
font's corresponding global pointer. Finally it returns a TRUE to 
signify successful completion. If at any point there is a problem, 
the function will return a FALSE. You can use the following 
popular calling style to invoke the Load_Fonl() function: 

it ( :Load_Font Csapphirel9") ) 



I 

. . . take co 

) 



action ... 



To actually use a font with the primitive TextO function you must 
first use the SelFont() function, to make it vour program's current 
font: 

SetFonttmy_rp, sapphirel9); 

You should inspect the Load_Font() function in Shell.c to con- 
vince yourself that 1 have designed it correctly. SAS/CsstrcmpO 
function is used to test the argument passed from the calling 
program. That's the same method I used in the Open_Mv_Screen() 
function to determine what screen resolution you wanted for 
your program Notice that after opening a font I test :ts size. 
Intuition has the characteristic that it will give you a font that 
closely matches the one you asked for if it cannot find an exact 
match. 1 don't want that feature. Finally, at the end of the 
Load_Font() function you will see a lone "return FALSE" instruc- 
tion. The purpose of that is to signal when a match could not be 
found for the string argument passed by the calling program, 
probably because it was misspelled. 

AUTOMATIC FONT CLOSING 

The required closing of fonts has been designed into the 
Close_Shell() function. It liappen$ automatically'. laVa a look inside 
this issue's Close_Shell() function to see how each global font 
pointer is tested before it is closed. An empty font contains a 
Mil and won't get closed. Note that passing a NULL to 
Intuition's CloseFontO function will crash your machine. That is 
in fact thevery reason why I designed the Close_Shell() (unction 
to automatically close fonts for you, rather than ask you to do it 
yourself. When you use a lol of different fonts, it is easy to gel 
mixed up and accidentally close one that was never opened, thus 
crashing your machine. By never closing fonts yourself, that is, by 
relying on the Close_Shell() function to do it for you, you will 
never encounter that problem. It isal ways best to hide dangerous 
operations within functions. 

You will find an example that uses my structured method of 
accessing fonts in the Font_Function drawer on the magazine 
disk You should agree that this new structured method is eosiei 
to use than resorting to basic principles evei \ lime. 

2.04's OUTLINE FONTS 

The new operating system contains three new fonts styles 
w hose sizes are adjustable o\ er a very wide range. They a re called 
outline fonts, and they are stored on disk in a format that is 
different from the older, bit mapped fonts. However, Commo- 
dore supplies a s\ stem tool, called Fountain, which you can use 
toconvert outline fonts intostandard Amiga, bit-mapped format. 
For example, using the Fountain you can produce a bit-mapped 
file for a lOOpoint Compugraphic Times font, and you can use 
that font from within your programs using the same techniques 
presented here in this article. Naturally if you want to share that 
program with friends you will have to include with it a copy of 
whatever font files it uses. 

ERROR FROM LAST ISSUE 

In the last issue I gave you some erroneous information 
having to do with allocation of memory for a border-data-arras 
Recall that the purpose of this array is to store pixel numbers 
representing points in a line drawing, and that it must be linked 
toa Border structure through the XY member. 1 told you last issue 
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thai .1 border-data-array had to be declared in chip RAM, bui I 
H as tt rong, You do not need to specify any particular type of 
memory for a border-data-array. 

Recall that there are two methods for allocating memory for 
an array, the static method and the dynamic method. The statk 
method is used when you know in advance the exact size thai von 
will need, when you know the number of points in vour line 
drawing. I said last issue that this static method required you to 
declare the border-data-array using SAS/C's special, chip data 
type.andthatasa result it needed lobe global in scope. That is not 
true. You can declare theborder-dala-arrav the same u a\ .is you 
do any other array, and as a result it need not be global. Note 
however that its scope must be such that it actually exists at the 
time the DrawBorderO function Is invoked. Thedynamic method 
of allocating memory for an array is used when you do not know 
In advance the exact size that you will need, when the number of 
points in your line drawing must in fact be calculated by the 
program itself. This method involves the use of AllocMem'o, in 
which you Specify, using variables, the amount and type of 
memory that you need I >.iid last issue that you had to use the 
macro MEM] (_ FflPas an argument to the AllocMemf) function. 
Thai is not true. You need not specify the type of memorv al all. 
Thus, using an example from last issue, the following declaration 
would work fine; 



a = 



(SH3RT-)AllocMen)2'U ine_count-POINTS) 'sizeof (SHORT! . 

Mat 

My errors last month do not affect whether or not vou need 
to use the static or the dynamic method of allocating an array, 
I hey affect only the type of memory that you specify in eai In ase, 

It turns out that there are manv other data structures on the 
Amiga that do require dala to be declared in chip RAM. I will be 
ting one next issue As » result it is easy to forget and 
accidentally specify chip ram when in fact you do not have to, as 
I did last issue. It is not the first time lhat I have made this mistake, 
and it probably won't be the last. The good news is that this error 
does not affect the operation.! I integrity of yourprograms 
tying chip RAM when in fact you do not have to is not harmful. 
I do however want to set the record straight on this subject. In 
contrast, forgetting to specify chip RAM when in fact vou need to 
can be disastrous. I hope I do not get caught making that mistake 
in these articles. 

LINE ANIMATION PROGRAM 

This program was first introduced several articles ago for the 
purpose of giving you some valuable experience compiling 
multiple module prefects using SAS/C. This issue I present its 
working parts, its algorithm. To facilitate its presentation, I have 
ported it to the programming shell that we have been developing 
together since that time. I have also enhanced it by using our 
newly learned skill, disk-based fonts 

CREATING A LINE WITH A TRAIL 

To create a line with a trail you draw several instances ot .1 
line, each one differing slightly in position. That is. you draw a 
group of lines that are spread out in a closely related, sequential 

pattern. In my program 1 draw |s) lines. To create a moving line 
with a trail, you must continue to draw new lines, while at the 



same time erasing older ones. The number of lines appearing on 
the screen must remain constant while you do this To give the 
appearance Of forward motion vou must add lines to one end ot 
the pattern and erase them from the other end, and to do that vou 
must keep track of the positions of all the lines in the pattern. 

USING AN ARRAY FOR COORDINATES 

An obvious way to keep track of the positions of lines is to 
store the coordinates of their end points in an array. Using index 
variables vou can keep track of which line you drew first and 
which one you drew last I Q create continuous motion you will 
want 10 eras*- the line at the trailingedge of the pattern and replace 
its coordinates in the array with a new one that is geometrically 
closely related to the one at the leading edge. For example, 
suppose I have a Implement array containing thex and y coordinate 
positions of the first 19 lines that I drew. The one I drew first j- al 
index position 0. It represents the line at the trailing edge of the 
pattern. The one I drew most recently is al position 18. It repre- 
sents the one at the leading edge. I might start by erasing the line 

at position t», recalculating a new one based on the position of the 
one al index position 18, storing its coordinates in the arraj al 
position 0(ovcrwriting the old one), and then finally drawing the 

line. The line at index position would now represent the new 
leading edge of the pattern. I could then go to in. lion I of 

the array, and again erase, recalculate (based this time on the 
position of the line stored at index position 0), store, and draw I 
might continue in this manner until 1 reach index position 18, the 
topof the array At that point I simply jumpback down to position 
Oand start all overagain. Thus I cycle through the array, each time 
erasing old lines, and recalculating and drawing new ones I can 
useC's modulus operator tocycle through an array lor example, 
in the following code the 20 element array is cycled five times 

short array|201 ; 



fortindex = 0; 11 



nri 



■ ■ ■ 



When index — 21), then index 20 .= = 0. Thus when the index 
reaches the top of the array the subscript) index %20| jumps back 
down to the bottom 

CIRCULAR QUEUE 

There is an official name for an arrav u-.ed as I h,i\e described. 
It's called a circular queue. The name queue is used to describe 
any structure in which data is processed on a first-in-first-out 
basis, or FIFO. In the above example the line that is erased (taken 
out) is, il wavs the oldest one, the one that has been in the array the 
longest, the one that compared toall the others got there first The 
queue is called circular because of the way 1 cycle through il, 
using the modulus operator When I increment from the the last 
position I automatically jump back down to the first Although in 

reality every array consists of a linear section of memory, using il 

this way makes it seem like it's doubled back on itself, like a 
donut. Hence the name circular queue. 

DRAWBORDERO FOR DRAWING AND ERASING 

Intuition's Border structure has SORie nice advantages for 

implementing the line animation program, lean declare an array 
of Border Structures where each one draws one line, similar to 
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how I drew the rosette pattern List issue Each BordeJ strut ture ifi 
linked to four elements of .in array which contains the coordi- 
nates rf all the lines in the pattern. I call this the IJi'rdrr-J.it.i- 
«irr.iv I can then link these structures together and render lliem all 
.it once usinga single l>awBorder()inslruction. In addition, since 
each Border structure specifies its own particular pen number, I 
can erase lines simply by specifying pen number zero for the one 
containing the line I wan) to erase Note that in my program fuse 
a20-elementarray from which 1 draw a 19-line pattern. The extra 
element is used to automatically eras,- old lines .,> new ones are 

added 

Inmost implementations oi this line animation program the 
erasing of the last line overwrites other lines as the pattern moves 

around screen, creating ugly spots. To remove this effect, you 
must redraw all lines in the pattern immediately after each old 
line is erased. With Intuition's I )ra»Burdei( » (unction this is easy 
to do. Recall that a linked list of Border structures is rendered 
sequentially, that is. the first onv in the list is rendered first, then 
the second, etc. So, to guarantee that the oldest line in the pattern 
is erased ttrst, followed by redrawing all the others, I perma- 
nent K set the front Pen member oi the Iirst Border stria lute in Un- 
linked list to the background color, zero, and then copy the 
coordinates of the old line that 1 wanl to erase into the tirst four 
positions of the Border-data-array. Thus the old line is Linked to 
the Border structure whose Frontl'en is set to zero. With a single 
DrawBorderl) instruction the computer erases the old line then 
draws every other line in the pattern. On most computersdrawmg 
so many lines would bog the system down so much that the 
animation would be ruined. Not soon the Amiga, because of the 

speed of DrawBordi'iO. Below 1 show the Function Init.LinesO, 

which accomplishes the initialization ot the Border structures. 



Frontl'en of the tirst Border structure is set to zero. It will do the 
erasing. All other structures in the list have their Frontl'en mem- 
bers set to ^nv. Each Border structure is linked through the 
NextBorder member, except for the last which is grounded (as- 
signed a NULL), in addition each Border structure is linked to its 
own section of the Border-data-array, in which coordinates for 
the various lines will be stored. The first Border structure is linked 
to the tirst lour elements of the array Refer to page 59 of last issue 
for a hierarchical diagram of an equivalent structure, which was 
used Iodrai\ the rosette 

COORDINATE CALCULATIONS 

The calculations of the coordinates for the endpoints of each 
line are based on a trick of trigonometry. Recall that a circle can 
be drawn by using the SINE and COSINE functions. Look at the 
example on disk called Circle. Now, imagine two points travel- 
ling around on the circumference of that circle. Also imagine that 
those two points are connected by a straight line. The result 
would be a revolving straight line, like a fan spinning around. 

It von change the relative frequencies and phase angle for x 
and y in the above program you get what is called a Lissajous 
ligure. l,ook at the example on disk called Lissajous. You will see 
that the x angle has been multiplied by 3, and the y by 5. Also a 
phase angle has been added to the y angle. You can create all 
kinds of interesting patterns just by playing with the frequencies 
and phase angle in this program. Now imagine two points 
travelling around on the circumference of this curve, and a 
straight lino joined between them. This is in fact exactly how the 
line motion of my program is calculated. There are other ways to 
calculate the motion of a line, some creating more realistic mo- 
tion. This method is convenient. 



VOIL- . nest struct Border 

'poii. 

I 

BYTE i; 

■ Lalize Be : 

and Link them to 






for I - . ; . I 

I Kdge = 0; 
.ige = 0; 

Lines [i ] .Front Pern = 0; 

! 
aacWen 
Lines 1 1 1 . DrauWod'.- 
Lineslil .Count 

• 

-9) 

: 



else 

I 



ILL; 



SPEEDING UP TRIG FUNCTIONS 

Trigonometric functions are very time intensive on any 
computer, requiring the use of floating point libraries. That 
would slow down an animation on any computer. To solve that 
problem. I create a look-up table of trig values for sin() and cos(). 
Note that I use the names Sin and Cos (first letter capitalized) for 
these tables. They are integer arrays and I store in them the 
calculated pixel values corresponding to the sin() and cos(> func- 
tions from the floating point library. I do this for all angles in one 
degree increments. Thus when my code usesSin)] orCos[], it is 
not calling functions in the slow math library, but integer values 
in a faster look-up table. Take a look at the code which generates 
these look-up tables: 

s.xmin = 
s.xmax = i.0; 
s.ymin = -1.0; 
s.ymax = 1.0; 

:a:e_Window(rry_window) | 
I 
. . .corrective action. . . . 

forlangle = 0; angle < 360; --angle) 

Si: sin(Rad([D0U3LE)ang;le))); 

Cosiangiej = Fx(cos{Rad( (DOUBLE) angle J J) ; 
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Please notice Ih.it 1 have scaled the screen to +/- 1.0 in both the 
horizontal and vertical directions, and used Fx{) and FyO pixd 
conversion (unctions for calculating values at each angle. Thus 
the values stored in the look up tables represent horizontal and 
vertical pixel coordinates (or a point rotating around a unit drde 
which (ills the screen. Actually, it is an ellipse. Without screen 
scaling and pixel conversion functions, I don't know how I would 
dothiv 

COLORS 

I use C's bitwise AND operator to select a range of random 
numbers for color selection: 

SetRGW(my_svp,1.8*(rand()&7),8+(rand0&7),8+(rand{) o ..7)) 
S,tKc;B4(my_svp,2,8*(rand()&7K8+(rand0&7),8*(rand()%7)) 
SetKGB4(m>vsvp,X8»(rand()&7),8*(randO&7K8»(rand()%7)) 

By choosing random values between zero and 7. and then adding 
8, 1 select the brightest half of the Amiga's -1096 colors. 



points[4), not points[0J. Remember that the first four elements are 

linked to the Border structure whose Front Pen member is as- 
signed zero It is used tor erasing, not lor drawing. The lines 
calculated by the following loopareclosclv related geometrically 
because each one uses the next incremented value of its angle 
variable. Each variable cycles through 360 degrees using its own 
constant step value The result is the coordinates of two points 
moving around the circumference o( a I IssajOUS figure at differ- 
ent, but constant, speeds. 

80; i 



pOin' 
point .-■ 
poincs[i.2) 
points 

) 



Cost fang 
Sin[ (angle_yl 
Cos[ (angle_x? 
Sinl (angle_y2 



phase_x. • - 

phase_y2) % J60 



PHASE ANGLES 

I then select phase angles for both 
the horizontal and vertical coordinates 
of each end point of a line. 

phase_xl = 2*(rand( 
phase_yl = 2*(rand()%6); 
phase_x2 = 2+(rand()%6); phase \2 
2+{rand()%6); 

Although I use the variable name 
phase, what I reallv mean here is an 
angular index value. The angular 
measure of the x and y coordinates of 
each endpoint of the line will be in- 
dexed using different values, each 
between 2 and 7 degrees, thus giving 
them constantly changing value and 
relative phase. As a result the two 
points travel around thecircunifercnce 
of the Lissajous figure at different 
speeds. This creates morevariety. Next 
1 randomly pick the initial angles, 
angle_xl through angle_y2: 

angle_xl = randi 
angle_x2 = rand()%360; 
angle.yl = rand()%360; 
angle_x2 = randl 

LINE INITIALIZATION LOOP 

Now for the mea tot the algorithm. 
I place into the Border-data-arrav (In- 
coordinate values of 19 lines. Each end 
point has two coordinates, a horizon- 
tal and a vertical. Thus it takes lour 
elements of the a rrav to store one line 
Notice that I start the first line at 
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ANIMATION LOOP 

And here is the main animation loop: 

3000; U 

I 
/• 

opy data from po-. '76 to position 



:.en put ni 



• 






■■ 



B(0] = p- 

point: _■ ■ ■;) % 360]; 

cs II] 

points(i%76.5] = Sin! «_yl| % 360]; 



points[2) = j 

points|i%76»6] = Cos Mann. 



* 360J; 



points[3] 
points(i%76«71 = 



6*7]; 

phase_y2l % 360]; 



DrawBorder(my_rp, Lines, 0, 0); 
if (Use ;dow) ) 

Each hnu' through the loop four coordinate .ire copied starting 
from the current position in the queue, (i' 7"- 4). which repre- 
sents the oldest lino in the queue, into the first (our elements in the 
Border-data -array, where it will be erased Next the coordinates 
starting at thai same current position. (i%76<-4), are replaced by 
new values, calculated by incrementing forward the angle vari- 
ables .K is Bus incrementing of the angle variables thai causes the 
positions of new lines to be closely related geometrically, thus 
producing a smooth flowing pattern. Finally DrawBorderf) is 
invoked to both erase the line whose coordinates were copied into 
the first position, and to draw the remaining W lines, including 
the most recently calculated one. The line most recently calcu- 
lated (at the present queue position) appears at the leading edge 
of the pattern. The drawing process occurs so fast that vou never 
notice that me lines are actually being drawn out ot M-queiwe 

The last instruction in the loop i> a call to Userl'ort.messageO, 
our newly designed polling (unction. It allows your program to 
process the animation while at the same time check tor keyboard 
response, indicating that the user wants to terminate Iheanimation. 
The animation loop exi-cutes 30tX) times, then drops out to re- 
calculate initial angles and phase angles, thus treating a different 
pattern. 

IntuiText STRUCTURES AND FONTS 

in the init .Titled function of I Ine. Anim.c, you will see how 
fonts an- used with the higher level PintlTextO function Recall 
that PintlTextO renders text which has been previously linked to 
any number of linked IntuiText structures. To get different fonts, 



each Intui I e\t structure is linked to a different Text Attr structure 
through its ITextFont member (Flgure#3) 

The calculations for centering text on the screen are done in 
the same manner as in our earlier l>isk_Fonts.c example. Notice 
that to calculate horizontal screen positions I had to use the 
TextU-ngthO function, and to do that I had to first change the 
current font using the Set Font () function. The I^ftEdge member 
of each IntuiText structure is assigned a calculated horizontal 
posit ion for its particular string Perhaps you think it a bit tedious 
to have to perform all these calculations. The good news is that 
using this higher level PrintlTextf) method, as opposed to the 
more primitive Text() method, you have to perform these calcu- 
lations only once. The main program can render the text as many 
times as ,t wants, without having to perform any additional 
calculations. The text appears properlv centered every time be- 
cause the horizontal and vertical positions of each text string have 
been pre-calculated and stored in the Left Edge and TopEdge 
members of their respective IntuiText structures. 

RESOLUTION INDEPENDENCE 

I here are two versions of the compiled line animation pro- 
gram on disk. The only difference between their sou decode is the 
graphic mode specified in the call to Open_Shell()- This is pos- 
sible because I have used system values in my calculations of text 
positions, and the Fx() and Fy() pixel conversion functions for the 
positions of lines. The program is resolution independent. 

WHAT'S NEXT 

In the next issue I will present a different graphic rendering 
Function, DrawImageO- We will be leaving the Rosette and Line 
Animation examples behind us, and going on to a new example, 
the game of LIFE. This game is really a simulation invented by 
Bntish mathematician ]ohn Horton Conway. !t is not only filled 
with intrigue, but also gives me an opportunity to present some 
interesting and challenging programming concepts. You will see 
that Intuition's Drawlmagef) function allows you to easily design 
this and other complex board games. I hope to see you next issue. 
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PART 4: ADDING NEW OBJECTS AND FUNCTIONALITY 

by FOREST W. ARNOLD 

Introduction 

!nPart3ofthisse^ies(/\C'snT/^V2.1) / wesawhowtouseCprog^a m mingandsoftwarepackaKinK 
techniques to implement an object-oriented CAD system. We then used the techniques to implement 
graphical shapes, polylines, and polygons as full-fledged objects, and put them to use in our mini- 
CAD program. In mis article, we will use the techniques we developed last time to add circles and 
rectangles to our program. We will also see how to add new functionality to our existing objects by 
implementing "copy" methods for all of them. First, let's take another look at the major features of 
object-oriented systems, and review how the features are implemented in our miniCAD program 



A Second Look ol Object-Oriented Programming 

Objects .ire software models ol some entity or activity. The 

models consist of Iwo parts: a data part and a behavior part. The 
data part is a description of an object's individual data elements, 
and the behavior part is a description of the actions which an 
object performs and how ii does them. The entities In CAD 
systems are geometric: lines, circles, text, and others. When we 
use a CAD program, we can move lines, resize circles, rotate 
polygons, and do many other things with these geometric enti- 
ties We generally think of lines, circles, and other geometric 
entities as passive objects which do not "do" anything. However, 
when we model objects using an object-oriented approach, we 
look at all the actions we want a program to do, and then write 
code which enables each type of object in the program to perform 
Bona of interest. We assign the actions of an object -oriented 
program to the software objects in the program. So, in an object- 
oriented CAD program, lines and circles "know'' how to move 
themselves, resize themselves, and perform many other actions. 
Thedata part of an object is just a conventiona i da ta structu re, 
and the behavior part is simply a set of procedures and functions. 
If you look at the data structures and code we defined last time to 
implement shapes, lines, and polygons, you will see that they arc- 
no different from the structures and code in a CAD program 
which is not object-oriented. The key factor which differentiates 
object-oriented objects from those which are not is the linkage 
between the data and behavior (code) parts of the objects. An 
object's data is tightly coupled to its code. After an object is 
created, the only way to execute its code is through its data, and 
the only way to access or modify itsdata is through itscode.Inour 
object implementation, the data for an object is linked to its code 
with a structure pointer. The pointed-to structure contains func- 
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tion pointers to the object's procedures. I call the structure con- 
taining the function pointers a "class structure," since it links 
objects io their classes' procedures. 

Object-oriented pro^rammerscreate new type- oiol>|edshv 
definingnew classes Classes are abstract (programmer-defined) 
types rhej Specify and implement the data structures and 

tunctionality for a single type of object. Clasv^ons],|,»f private 
data definitions and code for their objects, and public interlaces 
lor applications winch access and use the classes' objects. The 
private date structures and code for classes are their implemen- 
tation The public class interlace- specify how application code 

interacts wuh classes and their objects The separation of a class's 
implementation trom its specification (how to use it) is called 
"encapsulation ." Encapsulation helps reduce a program's com 
plexity, reduce the effort required to maintain and modify it, and 
increase its reliability. 

In our approach to object-oriented programming, we en- 
capsulate our classes by packaging their code and data into 
several files. We implement our classes with three files, and 
implement their application interfaces with two files. The three 
implementation files are a "private" include file, a "public" 

include file, and a source code file. Data structures and proce- 
dures used only by classes ,,re declared in their private include 
file, and data structures and procedures used bv application code 
are declared in their public include file. AU the procedures which 
implement the functionality of a class's objects are placed in a 
single source code hie. They are defined with C's "static" scope 
qualifier, which limits their visibility to their source code file. 

Two files are used to specify how application code interacts 
with a class's objects. One hie contains the source code for the 
procedures an application calls, and the other is just the include 



file which declares Ihe procedures. These two files define and 
declare .1 "class interlace" between application code and Ihe 
class's objects and their procedures For the shape objects in our 
mini-CAD program, the three implementation files for their class 
(shape class) are shapeClass.c, shapeClass.h, and shapeClass P.h. 
The twoclass interlace tiles (or application code which uses shape 
objects are shape.c and shape.h Figure 1 shows how all these tile- 
are used. 

Ihe following structure defines our shape objects; 

typed- ■ 



double 



■ 

bounn 



The "class" member of the structure provides the linkage 
between shape objects and their Code It is a pointer to a structure 
named "shapeClass". This structure is defined in shapeClass.c 
and exported as .in opaque (void") type in shapeC lass.h. The 
shapeClass structure contains Function pointers which point lo 
the procedures used with shape objects. Shape obnvts ,i ii- treated 
as shapeObjecM structures. When they are created, the "class* 
structure member is initialized to point to the shapeClass strut 
lure. Code which knows how shape objects are defined; and 
knows which function pointers are in the shapeClass structure. 
can call the procedures lor shape objects using the shapeClass 
pointer Figure 2 shows how shape objects are linked to their code 
with the shapeC lass structure pointer. 

New classes are created either from scratch, or .ire derived 

from existing classes In Pari 3 of this series, we created three 

classes shape class. Ime class, and polv class \\ ,• , teated shape 
dassasabrand neu class, derived line class from shape class, and 
then derived poly class from line class. Classes which are den \ ed 
from existing classes are called "subclasses," and the classes they 
are derived from are called their "superclasses,'" Subclass objects 
arelike the superclass objects from which they are derived. They 

have the same data elements and class interlace procedures RS 
their superclass objects. Subclass objects perform the same act ions 
as their superclass objects. Thev may also have data elements 
their superclass objects do not have, and execute actions their 
superclass objects do not perform. 

For example, the structure defining our line objects is: 

■ 



■ ■ 
■ 



* 



- 



■ ■ ■ 
bounding box « 

■ ■ 



• 



■ 



Except for the addition of a "points" member, the structure 
for line objects is identical to the structure for shape objects. Line 
class implements the same actions as shape class, but some of 
them are implemented differently. Line objects and shape objects 
do the same things when their "displavit" and "pointToObjcctO" 
procedures are called, but thev do them in different ways. Line 
class .i|so implements actions which are not spci ified bv shape 
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class. These actions are for finding, dragging, and moving a line 
object's individual points. In the same way thatOPJ C Ct and subobject 
structures sharecommon members, thi- class struct uresloi 1 Lisvrs 
and their subclasses share common members. Except for the 
addition of new function pointers, the class structure definition 
for line class is identical to the class structure definition for shape 
class. 

Classes and their subclasses model hierarchical "is-a" rela- 
tionships between objects: a line "is-a" shape, and a polygon "is- 
a" line. Although a line is a shape, and a polygon is a line, both are 
specialized versions of their superclass objects 1 )bjcct systems 
provide "inheritance" to support modeling "is-a" relationships 
between objects. Subclass objects inherit both data definitions 
and behavior (implemented with procedures! troni their super- 
class objects. Inheritance not only supports modeling hierarchical 
object relationships, it also provides a stronger form of code 
sharingand code reusability than that provided by code libraries. 
As a result, in object systems, new classes of objects can usually be 
created from existing classes with very little new code. 
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We implement inheritance in our object system with several 
different programming techniques. However, each technique is 
based on "structureoverloading." A structuredefined by adding 
new elements to the end of an existing structure "overloads" the 
existing structure. As an example, the structure for line objects 
overloads the structure for shape objects. By overloading the 
structure for shape objects, line objects automatically contain 
(inherit) thedata definition lor .shape objects. Structure overloading 
also permits the procedures defined for shape objects to be used 

for line objects. Since the structure members common to both line 
objects and shape objects are in the same positions in their 
structures and have the same meanings for both types of objects, 
the shape object procedures can be safely used to manage the 
"shape part" of line objects However, theopposite is not true: the 

line object procedurescan not be used for shape objects since they 
access the "points" member of the line object structure, and shape 
objects do not have a "points" member. 

The class structure for line objects, lineClass, overloads 
shapeClass, the class structure for shape objects. Except for 
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Figure 3. Linking Objects, Classes, 
and Superclasses 



pointers to procedures for the new actions specified by line class. 
the ImeClass structure is identical to the shapeClass structure. It 
contains the same members as shapeClass, and the members are 
all in thesame positions as they are in shapeClass Hie procedures 
which manage and access the members of the shapeClass struc- 
ture can also manage and access the members of the lineClass 
structure that are common to both shapeClass and lineClass. 
These are mainly the class interface procedures for shape class, 
which are in the file shape.c. Thus, by overloading the shapeClass 
structure, line class automatically inherits the class interface 
procedures defined for shape class. 

What about the procedures in the file shapeClass.c which 
implement the actions for shape objects? I'hev are not visible 
outside their file, so how can they be used with line objects? Three 
programming techniquesallow the procedures written for shape 
objects tobe accessed and used for line objects. The three techniques 
are superclass dispatching, procedure chaining, and procedure 
substitution. All three techniques rely on the knowledge that 
class Structures for subclasses overload the class structures of 
their superclasses, and that class structures contain pointers to 
theclass structures they overload. Figure 3 shows how objects are 



linked to their class structures, and how class structures of 
subclasses are linked to the class structures of their superclasses 

Superclass dispatching is the simplest of the techniques. 
Subclasses know which procedures are in their superclass, know 
how to access the class structure pointer for their superclass, and 
know how to access pointers to their superclass's procedures 
from the class structure. Thus, procedures in subclasses can call 
procedures denned by their superclasses. Superclass dispatching 
occurs when a procedure in a subclass accesses and uses a 
function pointer to call (dispatch to) a corresponding procedure 
in its superclass. Superclass dispatching is commonly used to 
augment the actions performed by a subclass's objects. Line 
class's setvalue() and getvalue() procedures perform superclass 
dispatching by calling shape class's setvalueO and getvaluefj 
procedures. 

Procedure chaining is easier to explain with an example 
Object destruction is a two-step process: first, any internally- 
allocatcd memory is freed by calling the "deallocate" procedures 
of an object's class and all its superclasses, then the memory 
allocated for the object itself Is fr ee d. I lere is a code fragment from 
deleteShapeO showing how objects are freed: 



I nhapeC I 

if I ahapeC- 

(voidl I'lha! 
ahapeC - get $>-»•• 



The "while" loop follows the chain of superclass structure 
pointers stored in the class structures. Inside the loop, the 
"deallocate" procedures lot an object's class .,,ui ,,|1 ,is super 
classes are called to free any internally allocated memory. The 
process of calling the "deallocate" procedures for the object's 
cl.iss.mdallits superclasses by following class structure pointers 
is called procedure chaining. If the procedures are called begin- 
ning with an object's class, then proceeding up through its 
superclasses, the process is called "upward chaining ." If the 
procedures are called starring with shape class, then proceeding 
down through subclasses until the object's class is reached, the 
process is called "downward chaining." Upward chaining is 
implemented by iterating through class structures, following the 
superclass pointers stored in them, and calling procedures for 
each class. Downward chaining is implemented with recursion: 
recursive procedure calls arc made for each superclass until the 
root class (shape class) is reached. As the recursive procedure 
calls unwind, the procedures for each of an object's superclasses 
are called. Downward chaining bused in createShapeO to initial- 
ize data values for newly created objects, and upward chaining is 
used in deleteShapeO . Both of these procedures are in the source 
file shape.c. Figure 4 shows the order in which procedures are 
called when procedure chaining is used. 

The third programming technique we use to implement 
inheritance is procedure substitution. This occurs when a super- 
class substitutes a pointer to a "real" procedure for a "dummy" 
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procedure pointer in the classstructure of one of its subclasses. A 
dass specifying a procedure defines a dummy inheritance proce- 
dure corresponding to the real procedure and makes ii available 
toitssubclasses-Subdassesthatneedtoinheritthe real procedure 
place the pointer to the dummy procedure in their class struc- 
tures The firs) time an object is created, its class structure is 
Initialized using superclass dispatching: the class structure is 
sent to each of the setup! ) procedures oi the class's superclasses 

rhesetUpO procedure in each dass defining a procedure exam- 
ines the class strut lure sent to it, looking for a pointer to a dummy 
inheritance prwedurecorres ponding to a real procedure it defined. 
It the pointer to a dummy procedure is found, it is replaced by a 

pointer to a real procedure defined by the class. Procedure 
substitution ts implemented in the setupfl procedure of each 
Class. You tan see how procedure substitution works by tracing 
through the dasssetupO procedures tosee how poly class inherits 
the "move" procedure defined by line class, and inherits the 
"moveDrag" procedure defined b> shape class 

Structure o\ erloading also lets us implement "polymorphic 
procedures" in our object system. Polymorphic procedures can 

be called tor an y object, regard less oi their type, The polvmorphic 
procedures take tare oi selecting and calling Ihe procedure-. 
Which are Correct lor the type of object sent to them. In our object 

system, polymorphism is implemented using overloaded object 

structures, overloaded class structures, and function pointers. 
Since all our objects are created by o\ erloading the shape object 
structure, and all our class structures are created In overloading 
Shape dass'sdassstructure / theclass interface procedures defined 
lor shape class can be used tor all OUT classes and objects fa 
display any object, no matter what type ol object it is, our 
application code calls displayShapeO< rhe same is true for all the 

class interlace procedures in shape c I hey are all polymorphic 

pro. edures. Ik-cause oui objects and class structures are defined 

with structure overloading, the class interlace procedure- tor a 
class are polymorphic tor it and all of Its subclasses I lowever, the 
opposite is not true lor example, the procedure* dehned in line.c 
. an be used tor hues anil polygons, but not for shapes, sinceshape 

objects do not have a "points" Structure member, and the 

shapeC las- structure does not have the hndl\>int0,rnovel'ointo, 

mu\ dragl'ointO (unction pointer- which are in the linrl (ass 
structure. Because of this, the polymorphic procedures in line.c 
need to make sure the objects sent to them are not shape obit, ts 
I hey make this determination by calling isSubClassO. This pro 
Cedure iterates through an object's class structures (using the 
"superclass" pointers) looking for a class structure pointer that 
matches the line class structure pointer. If a match is found, the 
object is either a line object or a polygon Object, In this case, the 
Object's clas- structure contains the function pointers the poly- 
morphic lineproceduresaccessandcalJ Notice that isSubQassQ 
doe- not perform actual low-level type Checking on ,\n object it 
only determines it .tn ohjett is a member of a general class ol 
objects Figure 5 shows how the polymorphic procedures tor 
shape tlass and line class select procedures by accessing class 
structures 

Now thai we have broadly reviewed the object system we 

implemented last time, we will now see turn to extend ii to 

include new functionality and new classes ol objects 



Adding New Functionality to Existing Classes 

A common CAD function we have not implemented is a 
"copy" function. Not only is this a common function, it i- a 
mandatory function tor any self-respecting c ,\l> svstem. St* we 
will now add a copy function toourmini-CAD program, and here 
is how it will work: 

I o , opv an object, a user will select "copy" trom the "action" 
menu. Next, she or he will move the mouse cursor over Ihe object 
to be copied and select the object by pressing mouse button I. The 
picked object will be copied and the copy will be highlighted. The 
user will move the highlighted copy to a new location by 
di agging it with the mouse. When the copy is positioned, the user 
will place it at its new position by pressing mouse button I. The 
copy will be unhighlighted and displayed at its new location. The 
copy action can be aborted by leaving the copy al it- original 
location. In this case, the cop) will be unhighlighted and deleted 
1 he copy action will remain in effect until a new menu action is 
picked. 
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We need to do several things to implement the copy action. 
We need to add .\,i>p\ menu item lo our action menu and write 
a copy "action" procedure to orchestrate the actions specified 
above. We also need to link the copy menu item to its action 
procedure More importaiUk . we need to add copy procedure- to 
our classes, and add a copy class interlace procedure for our 
action procedure to call. 

Our copy action procedure is named pickAndC op\ (J 
link the copy menu item to our copy action procedure the same 
way we linked our menu items to their code last time: bv over- 
loading Intuition's menullem structure and adding an 
"intuilxtenston t' structure to it. The overloaded menultem 
structure is called "mvMenu Itemj". it is defined in 
"glohalDefs.h". The intuiExtensionJ structure contains a pointer 
to an event handler procedure that is called when a menu item is 
picked It also contain- a pointer to a data structure called 
"mil)dta_t", The mi Data t structure contains a pointer to our 
top\ action procedure, pickAndCopy(|. When the copy menu 
item is selected, our event input handler, handlelnput(), retrieves 
ihe event handler function pointer trom the overloaded menultem 
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structure pointer. Handlelnput<) then calls the event handler. 
sending it Ihe miD.it.i_t structure pointer. The copy menu item 
evenl handler is "miSetActionO". It retrieves the pointer to our 
pickAndCopyO action procedure from the miDataj structure 
pointer and placesit into ourprogram's global state vector, which 
is called" world ".Uiter, when a button press occurs, handlelnpulO 
calls "window Eventf)" to take (.ire of it. If an action procedure 
pointer is in the world state vector, windowEventO calls it to 
process the button press event. For our copy menu item, 
pickAndCopyO is the action procedure windowEventO calls 
when a button press occurs. The copy menu item is defined and 
initialized in the file mcnu.c, and pickAndCopyO is defined in 
tstObject.c and declared in ieHandlers.h. You may want to review 
how we linked Intuition's input objects to our application code 
and managed input events. The way this is done is explained in 
excruciating detail in Part 2 and Part 3 of this series. 

The action procedure to copy an object is almost identical to 
the action procedure to move an object. The only difference is thai 
Instead of moving whatever object is picked, we first copv the 
picked object, move the copy, then add it to the list of world 
objects. Here is the algorithm to copy an object: 

If an object is not picked, return. 

Copy the picked object. 

Highlight the picked object. 

Process "move drag" to obtain delta coordinate values for 

positioning the copy. 
Unhighlight the picked object. 
If the delta coordinate values are zero (copy not moved), 

delete the copy, 
Otherwtsej 

Insert the copy in the list of world objects. 

Move the copy to its specified location. 

Display the copy. 

As the algorithm shows, the action procedure to copv an 
object is simple. Except for procedures to actually copy objects, 
we already have all the procedures to implement our copy action 
procedure using this algorithm. Since all our objects are imple- 
mented with object-oriented programming techniques, we need 
to provide our classes with the ability to copy their objects. Each 
class either needsa copy procedure added to it, or needs to inherit 
a copy procedure from one of its superclasses. We will also need 
a polymorphic class interface procedure our application codecan 
call to invoke an object's copy procedure. 

The mechanics of adding a new procedure to an existing 
class are relatively simple: a function pointer for the new 
procedure is added to the class's structure definition, the proce- 
dure is defined, a dummy "inherit" procedure is defined, and 
finally, a class interface procedure is written. However, when a 
doss structure definition is modified, the class structure defini- 
tions of all its subclasses are affected. This is because they over- 
load the class structure definition of their superclass. Before 
adding new functionality to a class, we need to identify which 
class the functionality will be added to and find all its subclasses 
so we can update them. Since we need the ability to copy any 
object, we will add the copy protocol (the procedure, its linkage, 
the way it is expected to work, and its class interface procedure) 
to shape class, the root class of our class hierarchy. We will need 



to update line class and poly class since they are subclasses of 
shape class. 

What needs to be done when an object is copied? l : irst. space 
lor the copy needs to be allocated, then the values from the 
original object need to be copied into the new object.lftheorigin.il 
object does not contain pointers to any dynamically allocated 
memory, the copy is complete. However, if the original object 
contaias pointers todynamic memory, the dynamic memory also 
needs to be copied and a pointer to it needs to be placed into the 
new object. How does our mini-CAD program know which 
Objects contain pointers to dynamic memory, and how does it 
make sure the pointed-lo data gets copied? It doesn't! The only 
place this type of detailed knowledge about objects is available is 
in their classes. 

Our object structures are formed by combining structure 
"parts." Each subclass can define a new "part" and add it to an 
existing object structure If an object part defined by a class 
contains a pointer to dynamically allocated memory, that class 
needstobecalled when an object containing the part it define-, is 
copied. As an example, the object structure for a polygon is 
formed by adding a "line part" to a "shape part." The line part is 
a pointer to a linked list of points. When a polygon is copied, the 
linked list of points needs to be copied. Since lineclass defines the 
"line part" of lines, which is inherited by polygons, line class is 
responsible for copying the points. The bottom line is this: when 
an object is copied, each class which contributes dynamically 
allocated members to the overall object structure needs to be 
called to take care of copving the dynamic memory. If a class does 
not define any dynamic members for the object structure, the 
class does not need tobecalled when Ihe object is copied. To make 
sure objects are copied correctly, our copy class interface proce- 
dure will chain the objects' copy procedures in superclass to 
subclass order. 

Keeping the above discussion in mind, here is a step-by-step 
desi nption of how copy functionality is added to our classes: 

Step 1: Identify the class which specifies new functionality 
and add a function pointer to the class's structure part. 

Add the copy functionality to shape class so that all objects 
can he copied Add a "copy" function pointer to the 
SHAI'I-CJ'ART macro defined by shape class in the private- 
include file. shapeClassP.h. The copy function pointer is "int 
(*copy)(object_p object,objeet_p copy)". 

Step 2: Identify all sulvl.isses of the class modified instep I, 
and add the new procedure to the class and each of its subclasses. 
Make sure the class structures contain the new function pointer 
structure member. 

The class structures for all three of our classes (shape class. 
line class, and poly class) need to be updated. Since line class 
defines a dynamically-allocated member for line objects, line 
class needs a copy procedure. Shape class does not need a copy 
procedure, and neither does polv class, since lineclass takes (..ire 
of copying points tor polygon objects. Set the "copy" function 
pointers for the shapeClass structure and the polyClass structure 
to NULL. These two structures. ire init i.i ii/ed in shapeClass.c and 
polyClass.c. Define a copy procedure for line class, and set the 
cop) tunction pointer in the lineCtass structure to point to the 
procedure. 
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Step 3: Defoe a dummy "inherit" procedure and a class 
interface procedure tor the new function. 

Since shape class specifies the copy functionality, il is re- 
sponsible for defining the "inherit" procedure and the class 
interface procedure. The class copy procedures are downward 

chained (called in superclass to subclass order), so they can not be 
inherited by subclasses. Thus, for the copy procedure, we do not 
need to define an "inherit" procedure. 

From the atxn e Steps, we see that to add copy functionality 
to our classes, we only need to wri te two new procedures: a copy 
class interface procedure for shapes, and a copy procedure for 
line class. Here i> line class's copy procedure: 
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The procedure allocates memory using the number of bytes 
required for an object {stored in the class structure) and performs 
a bytewise copy of the original object into the new space. At this 
point, if the object does not contain any dynamically allocated 
memory, the copy is complete. However, copyShape() does not 
know this, so it calls copyObject() to chain through all the class 
structures for the class and its superclasses and call any copy 
procedures it finds in the class structures. Here is copyOb|ect(): 
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Line class's copy procedure initializes the "points" member 

in the copy of the original object to NULL, then loops through the 
list of points in the original object, copying and Unking them 
together. This procedure is added to lineQass.c. 

The new class interface procedure for accessing the classes' 
copy functionality is added to shape.c. Its prototype is added to 
shape.h. 1 [ere is the procedure: 
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Other than being recursive, which is always confusing, 
copyObjectO is pretty simple. Notice thai even if a class copy 
procedure returns an error, the recursion continues until all the 
object'scopypriKeduresarecalled.HcopyShapeO fails, the copy 
oftheobjectwillhedeIetedbycalIingallitsclasses'"deallocate()" 
procedures, so each class needs to make sure any copied pointers 
are initialized to a known state. 

To see how the copy procedures work, let's step through 
what happens when a polygon is copied. First, we select "copy" 
from the "action" menu. Our event handler calls miSetActionQ, 
which places a pointer to pickAndCopyO in 'he program's state 
vector, world". Next, we move the cursor over a polygon and 
Select it I he event handler calls windowivrntO to takecareof the 
button press. WindovvEventO looks for a pointer to an action 
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procedure in the Mate vector, finds the pointer topickAndCopyO, 
and calls it. PickAndCopyO calls findObjecM) to see it an object 
was picked. FindObjectO returns tin- pointer to the polygon we 
picked. PickAndCopyO then calls copyShapeO, our new class 
interface procedure. CopyShape() allocates memory for the poly- 
gon copy, and copies the values from the original polygon into the 
allocated memory. It then calls copyObjectl). CopyObjectO 
recurses, following superclass pointers until it reaches the 
shapeClass structure, which does not have a superclass. At this 
point, copyObjectO starts looking for pointers tocopy procedures 
in the class structures. The shapeClass structure does nol h.ive a 
copy procedure, so copyObjectO returns, popping the tineQass 
structure pointer off the stack. The lineClass structure pointer 
does have a copy procedure, so it is called. It copies the list of 
points from the original polygon into the copy and returns. Once 
again, copyObjectO returns. This time it pops the polyClass 
structure pointer off the stack. The polvClass structure pointer 
does not have a copy procedure pointer, so copyObjectO again 
returns, completing the recursive calls and returning to 
copyShapeO. CopyShapeO then returns the pointer to the newly 
created copy to pickAndCopy(). PickAndCopyO completes the 
copy action by calling moveDragO to obtain a location for the 
copy, inserting the copy in the list of world objects, moving it, and 
displaying it. 

After we add these procedures to shape.c and linet lass < . 
modify the class structure macro in shapeClassl'.h. modifv the 
( lass structures for all our classes, and recompile and link our 
tstObject program, we can create copies of any object. The proce- 
dures will even work without any modifications when we add 
new classes of objects to our program, which we will now do. 



TABLE 1. 


Shape Class Methods 




Method Kv«|iiircd 


('■mined 


Inheritance 


Symbol 




setupClass 


yes 


upward 


none 




initialize 


no 


downward 


none 




deallocate 


no 


upward 


nunc 




copy 


no 


downward 


none 




setvalue 


yes 


DO 


none 




get value 


yes 


DO 


none 




update 


yes 


no 


none 




displa> 


DO 


no 


inherit Display 




erase 


DO 


no 


inheri (Erase 




highlight 


DO 


no 


inheritHighlighi 




unhighlight 


no 


no 


inheritUnfaighugbi 




insendrag 


no 


no 


inheriilnscrtdrag 




movedrag 


no 


no 


iidwritMovedrasj 




sizedrag 


no 


no 


inberiiSizedrasj 




roiaicdrag 


no 


\H- 


inhenlRolalcdnig 




move 


no 


DO 


InheritMove 




resize 


no 


00 


inheritRestzc 




rotate 


no 


00 


inheri ( Route 




pointToObjeci 


no 


00 


inheritPoiniToObjea 




extent 


no 


DO 


inheritExient 





Adding New Classes of Objects 

Fxtensibihty is one of the major benefits of object-oriented 
systems. It is usually very easy to add new classes of objects to a 
base set of existing classes. If the existing classes are designed and 
implemented so their procedurescan be inherited by new classes, 
many new classes can even be added with very little code. 
Companies and software vendors are cashing in on this aspect of 
object-oriented systems by creating and marketing object-ori- 
ented application development frameworks. These object-ori- 
ented framework~ .ire just a Kise set of classes along with tools 
and documentation for creating new classes as subclasses of the 
base classes. The classes we developed last time, along with the 
techniques for adding new classes, constitute a stripped-down, 
manual framework for developing object-oriented two-dimen- 
sional CAD applications. 

To add new classes to our (or anv) framework, we need to 
know several things. First, we need to know what new classes to 
add. This is usually pretty simple to figure out. Next, we need to 
know which classes already exist, know how they are organized 
in an inheritance hierarchy, and understand the protocol thev 
specify. The protocol consists of the procedures classes .ire ex- 
pected to provide or inherit, how the procedures are called, and 
what the procedures are expected to do when they are called. We 
need to understand the protocol so we can determine which 
procedures to write and how to write them, and we need to know 
the existing class hierarchy so we can decide where to add new 
classes in the hierarchy. Finally, we need to know the mechanical 
details of how to "bind" new classes to a framework 

A minimum set of objects for professional CAD systems 
includes lines, polygons, arcs, circles, rei tangles, text, and splines. 
MostCADsystems offer more objects than these, but some do not. 

Our mini-CAD system al- 
ready has lines and poly- 
gons, so we need to add arcs, 
circles, rectangles, text, and 
splines to it. Of these five 
candidate classes of objects, 
we will add classes for circle 
and rectangle objects. If you 
understand how these two 
classes arc implemented 
and added to our frame- 
work, you should be able to 
add the remaining classes 
of objects to the program 
The low-level code for in- 
teractively creating and ed- 
iting arc, text, and spline 
Objects is pretty complex, 
but the techniques tor add- 
ing the classes to our frame- 
work are identical to those 
for adding circles and rect- 
angles. 

\ew classes are 
added to object frameworks 
as subclasses ot existing 
classes rhis is called 
"subclassing" by object* 
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oriented programmers Since subclasses inherit data and proce- 
dures from their Superclasses, deciding which existing class to 
subclass has a significant effect on how much work is needed to 
add a new class, and on how well it will work after it is added. 
Subclass objects are specialized versions of their superclass's 
objects, so a good way to decide which class to subclass is to Mini 
one whose objects are similar to the new objects. As an example, 
polygons ,ir,'.ilniost identical to polylines, so we added polygons 
to our class hierarchy by subclassing line class. Let's look at our 
classhierarchy toseewheretoaddrectanglectassandcircleclass. 

Our exiting c!.isN:nlu-[itance hierarchy is shown in Figure 6. 
Shape class is al the top of the hierarchy. Shape class models the 
behavior of a broad class of CAD objects, and the shape object 
data structure la bounding box) is a general representation for 
graphical objects. All classes are subclasses of shape class. Line 
( lass extends the shape class model to include graphical objects 
which can be modeled as sequences of points connected by line 
segments. Poly class models polygons by specializing polylines, 
ton mg their first and last points to coincide. 

Rectangles are almost identical to shapes The) can be de- 
fined with the same data structure, and shape class already 
Specifies the behavior we need for rectangles. For these reasons, 
we ma) be tempted to create rectangles by subclassing shape 
dassJ lowever, there is one catch: the shape object data structure 
models the horizontal and vertical positions and dimensions ol 
an) graphical object, so shape objects can only be rotated in 90- 
degree in, remenls. If we create rectangle class by subclassing 
shape class, we will have to override shape class's "rotate" 




sctupClass 

initialize 

deallocate 

copy 

setvaluc 

getvahw 

update 



displa) 

erase 

highlight 

unhighliglit 
insendrag 

movedrag 
nzedraa. 

totaled rag 

move 

resize 

rotate 

pointToObjed 

extent 



Initialize class structure. Resolveinheritance for subclass structures. 

Initialize object structure pan .especially internal pointers. 

Free internally allocated memory whenobjcci is destroyed. 

Copy internally allocated memory whenobject is copied. 

Modify object data values. 

Return object data values. 

Validate object data value modifications after setvaluc is complete. 

Allow, disallow, or change mod ifi cat ions. Perform additional actions if 

needed 

Graphically displas sell 

Graphically erase self. 

Graphically highlight sell 

Graphically unhighlight self. 

Process graphical interaction to establish initial object values when 

object created. 

Process graphical interaction to obtain delta values to move self. 

Process graphical interaction to obtain delta values to resi/c self. 

Process graphical interaction to obtain delta value to rotate self 

Move self by delta coordinate values. 

Resize self by delta scale values 

Rotate self by delta angle value 

Return distance from a point to self. 

Return bounding box coordinates 



procedure so our rectangles can be rotated at arbitrary angles. To 
rotate rectangles at arbitrary angles, we need points representing 
their comers in addition to the data describing the bounding 
boxesaround them. But we already haveclasses of objects whose 
dala structures consist of bounding boxes and points, and whose 
objects can be rotated at any angle. They are line class and poly 
( l.i-s Rectangles are closed polygons. However, they are special- 
ized polygons: theyalwaysconsistof foursides.and thesidesare 
joined at right angles. Since rectangles are specialized versions of 
polygons, we will create re, tangle class by subclassing poly class, 
overndingandspeciaIizingpolyclass l s"insertDrag"and' , r. 
procedures. 

Which class do we subclass to create circles? We could use 
polygons as approximations of circles, and subclass poly class. 
However, calculating and drawing the edges needed to approxi- 
mate a circle can be time consuming, especially when they are 
being resized or moved around. Besides, it is more "natural" to 
model circles as objects with center points and radii. This model 
let~ us easily calculate diameters, circumferences, and areas of 
circle objects. Our existing class hierarchy does not contain ob- 
jects which are similar to circles, so we will create circle class by 
subclassing shape class. 

In case you want to try your hand at adding arcs, splines, and 
text objects to our framework, let's briefly consider which classes 
to subclass to create these three classes of objects. Arcs are 
specialized versions of circles. Actually.circlescan be modeled as 
specialized arcs, but since we are adding circles instead of arcs, 
an s can be added by subclassing circles. Splines are similar to 

polylines and polygons. 
Splines, like polylines and 
polygons, consist of 
points connected by 
edges. The edges for 
polylines and polygons 
are simple line segments. 
For splines, the edges are 
curves whose curvature 
is determined by the lo- 
cations of the splines' 
points. Open splines can 
be added to our class hi- 
erarchy by subclassing 
line class, and closed 
splines can be added by 
subclassing poly class. 
Our class hierarchy does 
not have any class of ob- 
jects similar to text ob- 
jects, so text objects can 
be added to the hierarchy 
by subclassing shape class 
(text class will need a drag 
input handler which in- 
teracts with keyboard 
events instead of mouse 
motion events). Figure 7 
shows the entire class hi- 
erarchy for implementing 
a complete set of CAD 
objects with our frame- 
work. 
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Now that we have decided which objects to add to our 
Framework, and decided where to add them in the class hierar- 
chy, the next step is to look at the class protocol to determine 
which procedures our new classes need. A complete description 
of a class's protocol consists of two "specifications", and can be 
quite voluminous. One part of the protocol specifies how appli- 
cation code interacts with a class's objects. The other half of the 
protocol specifies the procedures classesare expected to provide, 
and specifies how they are expected to work within the class 
hierarchy. The function prototypes in the include files for our 
da$fl interface procedures {shape.h and linc.h) are pari of the 
protocol for application-object interaction. The function proto- 
types in the private include files for our classes are part of the 
second half of the protocol. However, in addition to information 
in the private include files, we also need a description of which 
procedures are required, which can be inherited, which are 
chained, and which ones can be overridden. A simple way of 
presenting this type of information is in a table. Table 1 shows this 
information for shape class, and Table 2 describes the action each 
of the methods is expected to perform. Tables 3 and 4 present the 
same information for the methods specified by line class. 

We see from the above tables that the only methods which 
can not be inherited by subclasses are those which are required or 
are chained. Since shapcclass specifies the method protocol for all 
our objects, it provides default procedures for each of the meth- 
ods it specifies It aUo provides dummy "inherit" procedures for 
each of its methods that can be inherited. Line class specifies the 
method protocol for itself and any of its subclasses, so it also 
provides default methods and dummy "inherit" procedures for 
the methods it specifies. Poly class does not specify anv new 
methods, so its protocol is the same as line class's protocol. 



TABLE 3. Line Class Methods 



Required Chained Inheritance Symbol 



tmill'oint 


no 


1111 


inhcnir-imll'oint 


dragPouu 


no 


no 


inhcntDragPoini 


move Point 


no 


no 


inherit Move Point 



We now know which procedures our new classes are re- 
quired to provide and which ones can be inherited, and have an 

idea about what our classes' procedures are supposed to do. We 
are almost ready to implement them. Be tore actually implement- 
ing a new class, we need to answer several questions Ihese 
questions arc relevant in any object system. However, the an- 
swers to the questions depend on how new classes are added to 
the particular object framework, or are defined using an objet I 
oriented language. Thequestions, and the answers for our Irame- 
work, are: 



1. Will the new class need to specify protocol in addition to 

tin- protocol specified by its superclass? That is, will the new class 
require methods in addition to those ol Its superclass? 

If theanswer to this quest ion is "yes", then the newel, issv 111 
need to define a "class part" containing pointers to the new 
methods. Theclass part isappended to the class siructureof anew 
class's superclass, overloading it. It will also need to define 
dummy inheritance procedures tor any future subclasses, and 
will need to provide class interface procedures so application 
code can access its new methods Line class is an example nt a 
class which extends the protocol specified by its superclass. 

Neither of our new classes needs methods other than those 
specified by their superclasses. Nevertheless, we will define an 
empty "class part" (usinga macro) for our new classes. Wedo this 
for two reasons. The first reason is for consistency in defining 
classes. The second reason is to make adding methods at some 
later date easier 

2. Will the new class's objects need data elements in addition 
to the data elements contained in their superclass's objects' 

If the answer to this question is "yes" (it usually is), the new 
class needs to define an "object part" containing the new data 
elements for its objects. The object part is appended to the object 
structureof a new class's superclass, overloading it. Theclass wil I 
also need to define "atoms" for the new data elements so appli- 
cation code can access and modify the data elements using our 
getShapeValuesO and setShapeValuesf) interface procedures. 

Circle class needs to define new data elements to describe 
circles, but rectangle class does not need to extend the object 
structure denned for lines and polygons. We will define an empty 
"object part" for rectangles anyway, 

3. Could the new class be useful as a superclass tor another 
class of objects at some future time? 

Unless a new class is rather specialized, the answer to this 
question is usually "yes." If so, the class should be designed and 
implemented so that it can be subclassed. Sometimes this is not 
easy to do. 

Both circle class and rectangle class are good candidates for 
subclassing. Circle class can be used to derive an "arc class," and 
rectangle class can be subclassed to create a "rounded rectangle" 
class. We will implement our new classes so thev can be subclassed. 

Implementing Circle Class 

The tir--t task to tackle when implementing a new class is to 
define the data structures for the class and its objects In our 
framework, data structures are defined in the class's private 
include file, lor cialeclass, the privateindudeffeisdrdeClassPJi 

(shown in Listing I). The structures we need lodetine are theclass 
structure and the object structure for circle class and its objects. 
Circle class does not need to extend the protocol specified bv 
shape class, so we do not need to define class part data elements 
lor its c!a-.s structure We simpl) define an emptv macro for the 
new class part, and append the macro to theclass par is defined by 
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shape class, creating a class structure typedefed as circleClassj. 
To manage circle object.-, we need to know their center points and 

radii Wecould actually extract this information from the bound- 
ing box defined for shape objects, and inherited by circle objects. 
I fowever, the bounding boxes for objects should be calculated 
from the dimensions of the objects* rather than the other way 
around, lluis. the structure forurcleobjects needs tocontam their 
center x,y coordinates and their radius. We define a circle part 
macro, consisting of these data elements, and append it to the 
parts defined by shape class to create a circleObjectj 
structure. 

Private include hies are included in their class's source code 
tile, and also included by SUDC lasses. In addition to data structures, 
they also contain declarations of any variables and procedures 
which subclasses may need or find useful. Subclasses of circle 
Class will need access to its class structure so they can use it for 
their superclass; thus the class structure .circleClass is declared 
in circleClassI'.h. Circle class defines several procedures which 
may be useful to subclasses, so they are also declared in 
drdeQassPJi 

After the private include file for a class is complete, we create 
its public include file. This file is included by both the class's 
source code file and by application code. The public include file 
exports a pointer to the class s .lass structure, and exports at- 
oms which identify data elements of theclass'sobjccts. Applica- 
tion code uses the class structure pointer to create the class's 
objects, and us, g the atoms to query and modify an object's data 
values. The public include file for circle class is in Listing 2. 

The final steps in creating a class (which does not extend the 
protocol specified by its superelassjaretodefineand initialize the 
class s atoms and its class structure, and to write the methods for 
the class. This is done in the class's source code (implementation > 
file. The implementation file for circle class is presented in Listing 
3. Before we can define and initialize theclass structure, we need 
to decide which methods to write and which ones to inherit, since 
pointers to the methods and the dummy inheritance procedures 
are placed in the class structure. 

I miking at rabies 1 and 2, we see that new classes are 
required to provide setupClass, setvalue, getvalue, and update 
methods New classes can not inherit Initialize, deallocate, or 
copy methods, since these are chained methods.Ctrcleclassdoes 
not define any dynamic data elements (pointers to internally 
allocated memory) for circle objects, so circle class does not need 
to provide initialize, deallocate, or copy methods. The remaining 
methods specified by shape class can be inherited or defined by 
subclasses. All these methods involve the geometry of objects. 
Since circles and shape* are not geometrically very similar, circle 
class needs to define most of these methods rhe only ones which 

canbesensibly inherited are movedrag.si/edrag.rotatedrag.and 
extent. Although the three drag methods can be easily imple- 
mented (and probably should be), circle class will inherit them 
The source code tiles for our classes are organized in four 
logical sections: the tirst Section contains forward declarations of 
the classes 'procedures, the second section defines and initializes 
the classes' atoms, the third section defines and initializes the 
classes class siructure.and the fourth section contamsdehnitions 
of the classes' methods. The tirst three sections are fairly self* 

explanatory, so we will concentrate on the implementation of 
circle dasS'S methods. 



Automatic method inheritance is implemented by ourclasses' 
setupo procedures. Circle class's setupO procedure is called the 
first time our program calls createShape() 10 create a circle or an 
object in one of circle class's subclasses (currently none). If the 
circleClass structure has not been initialized, setupO calls its 
superclass's setupO procedure, sending it the pointer to the 
circleClass structure. Superclasses are responsible for resolving 
inheritance for their subclasses, so shape class replaces the point- 
ers to the "inherit" procedures in the circleClass structure with 
pointers to the actual procedures defined by shape class. Circle 
class'ssetupO procedure then examines'the class structure pointer 
sent to it. If the structure pointer does not point to the circleClass 
structure, it is a pointer to a class structure of one of circle i 
subclasses. If this is the case, circle class is responsible for replac- 
ing any "inherit" procedure pointers with pointers to procedures 
it defines corresponding to the dummy procedures. The setupO 
procedure does this by comparing function pointers in the class 
structure with pointers to the dummy procedures. If the pointers 
match, the dummy procedure pointers are replaced with pointers 
to procedures defined by circle class. The setupO procedure then 
sends the class structure pointer on up to shape class's setupO 
procedure to finish initializing it. 

Circleclass'sgetvalu^) and setvalue!) procedures are called 
by getShapeValuesO and setShapcValues(), which are called 
from our program's pickAndEdit() and updateValues() proce- 
dures. Both the getvalueO and setvalue!) procedures examine the 
"arg" array sent to them, looking for the atoms defined by circle 
class. When oneofcircleclass's atoms is found, getvalueO assigns 
the appropriate value from the circle object to the "argl'tr" in the 
"arg" record. Likewise, setvalueO assigns the value from the 
"argPtr" in the "arg" record to the circle object. These assign- 
ments are made using typecasts so the values will be ass 



TABLE 4. Line Class Method Actions 

Mel 

findpoint 



dragPoint 
move Point 



Return pointer to the object's point 

which is within tolerance of an input 

point. 

Process gr ap h ical interaction to obtain 

delta values to move object's point 

Move object's point by delta 

coordinate values. 



correctly. When either of these procedures encounters an atom it 
does not recognize, it calls its superclass's getvalue or setvalue 
method to take care of the atom. 

As setvaluef) changes values for circle objects, it updates any 
of their other values related to the changed values. However, 
circle class's setvalue() procedure has no way of knowing when 
the coordinates of a circle object's bounding box are changed by 
shape class's setvaluef) procedure. None of our class's setvalue 
methods know when a setvalue method in a superclass changes 
an object's values. So that classes can maintain the internal 
consistency of their objects' data values, setShapeValues{) calls 
theirupdate melhodsafter an object's values havebeen modified. 
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I Jet ore sctShape Values!) calls an object's setvalueO procedure, it 
makes a "shallow" copy of the unmodified object. After the 
setvalueO procedure returns, the object's update method is called. 
Both the modified object and the unmodified copy arc sent to the 
updated procedure. The update) (procedure compares value* in 
the modified object with values in the copy of the unmodified 

object to determine which values were changed by tfwsetvalueO 
procedures. 

Circle class's setvalueO procedure update* the bounding 
boxes for ci riles when their radii or center coordinates are changed. 
Thus, the data for circle objects are kept consistent when their 
radii or centers are changed. However circle class's setvalueO 
proct dure is not responsible for the bounding box. itoms: it sends 
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these atoms to it* superclass's setvalueO procedure. Because of 
this, the bounding box coordinates of circle* are changed by 
shape class* setvalueO procedure. When this happens, the 
bounding box values will not be consistent with the radii and 
center value* rotakecareo! this condition, circleclass's updated 
procedure compare* the unmodified circle's bounding box coor- 
dinates with the modified circle's hounding box coordinates. If 
the bounding box values differ, the circle object was modified, 
and the update() procedure ad |iisisits values so the bounding box 
values, the radius, and the circle's center are consistent. Circle 
class's updated procedure also makes sure the bounding boxes 
for circle* are not modified to have unequal widths and heights. 
Circlcclass'sdisplavO.eraseO, highlight!), and unhighlightO 
procedures are almost identical. They call SetAPend to set the 
graphics foreground drawing pen and then call drawCircled. 
DrawCircleO calls the graphics library procedure I >rawF.Hipse() 
to draw circle*. DrawFllipseO requires two radii: a horizontal 
radius, and a vertical radius. In world coordinates, these two radii 
may be different for ellipses, but they are the same for circles. 
Unless the pixel x to y aspect ratio of the screen is 1 to I, the radii 
in -•> reen coordinates for circles will be unequal. To account for 
the screen aspect ratio, draw-Circle calls worldDistToViewDistO 
and sends it the circle's world coordinate radius as both the 
horizontal distance and vertical distance. World Dist I oView I )ist() 
transforms the radius values into horizontal and vertical view 
coordinate (pixel) distances, which are then used in the call to 
DrawEUipsefJ 



The procedure called to obtain the initial position and si/e ol 
a newly created circle object is insertdragO. This procedure sets 
up an array describing the new circle in view coordinates, then 
calls handleDragO to process the actual drag interaction. The 
array describing the circle is named 'cp'. Its data consists of the 
circle's center \- and center v -coordinates, and the circle's hori- 
zontal and vertical radii. The pick coordinates sent to insertdragO 
are used as the circle'so-nter coordinates, and its radii a re initially 
set to 0. The "drag draw" procedure handleDragO calls to erase 
and redraw the circle as the drag interaction progresses is called 
draglnsertCircled I his procedure erases and redraw* the circle 
by calling DrawEUipse(), When handleDragO calls 
draglnsertCircled, it sends it the change in the position of the 
mouse cursor from the initial pick point to the current cursor 
location as x .u^i \ -pixel of (set*. DragltiserK irclef) has to find 
the radius of the circle centered at the initial pick coordinates 
whose circumference also passes through the x- and y-offset 
coordinates, It also has to account tor the x toy aspect ratio of the 
screen. To account for the asped ratio, draglnsertCircled calls 
viewDistToWorldDistd to convert the pixel offset distances to 
world coordinate distances. It then uses the distance formula to 
find the world coordinate distance from the circle center to the 
cursor location (refer to Figure 8). Thisdistance is the radius of the 
circle. Finally, worldDistToViewDistO is called to determine the 
horizontal and vertical pixel distances corresponding to the 
world coordinate radius, and these values are used to draw the 
circle by calling DrawF.llipseO. After handleDragO returns to 
insertdragO, the same technique is used to calculate the i 
radius from horizontal and vertical offsets* After the radius is 
calculated, insertdragO initializes the circle object's data values 
and returns 

Circle class inherits shape class's movedragO, sizedragl), 
and rotatedragO procedures. These procedures are called to 
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interactively obtain delta coordinate values to move an object, 
relative scale values to resize an object, and a delta angle \ alue to 
rotate an object. The circle class procedures which perlorm the 
move, resize, and rotate actions are move! ). resizef i. and rotated 
Circle objects are moved by simply adding delta coordinate 
values to their bounding box coordinate* and their center coordi- 
nates, Shape class's sizedragO procedure does not constrain 
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objects K) resize with equal \- .mil y -scale values: objects cm be 

"stretched". If circle class's resize<) procedure simply applied the 
\- and y -scale values obtained by shape class's sizedragO proce- 
dure tocircie objects, they would become ellipses, unless thescale 
values wen? equal To prevent this from happening, circle class's 
resize<) procedure first calls shape class's resfzeO procedure to 
resize a circle's bounding box It then finds the center oi the 
resized bounding box, and uses these coordinates .is the circle's 
new center finally, it calculates the new radius for the circle. 
Using the smaller of the bounding box's width or height. It then 
adjusts the circle's bounding box coordinates. Circles are rotated 
with respecttoa point usinga standard rotation transform matrix 
(discussed in Parts 1 and 2 of this series). Circle class's rotated 
procedure constructs .1 rotation matrix and uses it to rotate a 
circle's center point around the rotation point. This moves the 
circle, so its bounding box coordinates are updated to reflect its 

new position 

The last procedure defined for circle class is pointToObi. 
This procedure is called to determine the distance between a 
point (usually the mouse pick point) and an object Finding the 
distance between a point and a circle is simple; it i.s the distance 
trom the point to the circle's center, minus the circle's radius. The 
distance from the input point to the circle's tenter is calculated 
using the distance formula 

Because circle objects are not similar to shape objects, line 
objects, or polygon objects, we are unable to fully exploit method 
inheritance to implement circle class. We can only inherit shape 
class's sizedrag, movedrag, rotatedrag, and extent methods. 
Rectangles are constrained versions of polygons. Since rectangles 
are polygons, we can create rectangle class as <i subclass 01 po!\ 
v lass and inherit moM of the method-, it needs. 



ments \evt, we create the classy private include file and its 
public include file. We then decide which methods must be 
implemented for the class, and which can be inherited. Finally, 
the source code file is created, and we get down to the work of 
actually coding the class's methods. 

Shape class and line class specify all the methods rectangle 
class needs, sti we do not need to add any function pointers to the 
class structure defined by poly class. Line class specifies the data 
structure needed to represent lines and polygons, and thus 
rectangles, s. 1 we do not need to add any new data elements to our 
superclass's object structure. Since rectangle class does not need 
to add data elements for its objects, we also do not need to define 
any "atoms" for rectangle objects. In short, rectangle class can 
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Impie-menting Rectangle Class 

To implement rectangle class and rectangle objei ts we fol- 
low the same steps we followed to implement circles. The first 
step is to decide it rectangle class's class structure needs any 
function pointers in addition to those specified by its super- 
* lasses, and decide il rectangle Objects need am new data ele- 



simply inherit the cl.iv, structure, the object structure, and the 
atoms it needs from its superclasses without extending the struc- 
tures or adding new atoms. Nevertheless, for the reasons men- 
tioned earlier, we will define empty "class part "and "object part" 
macros and append them to the class structure and object struc- 
turedefined by poly class. The macros, and theclass structure and 
Object structure for rectangle class and rectangle objects .ire 
defined in rectClassP.h, which is in listing 4. We also export 
rectangle class's class structure in rectClassP.h so any future 
subclasses can use it for their superclass pointer. The public 
include file for rectangle class is shown in listing 5. It make- a 
pointer to rectangle class's class structure available toapplication 
code. The structure pointer is needed for creating rectangle 
objects. 

At this point, we have defined .our data structures and 
created our class's include files. The next step is to determine 
which methods to implement. Since we are implementing rect- 
angle class as a subclass of poly class, it will have the methods 
specified hv line class inaddition to those specified by shapeclass 
The protocol for shape class requires rectangle class to provide 
sctupClass, setvalue, getvalue, and update methods. Rectangle 
class can not inherit initialize, deallocate, or copy methods/ since 
these are chained methods. Like circle class, rectangle class does 
not define any dynamic data elements for its objects (the "points" 
data element is defined by line das,). so it does not need to 
provide these methods. The remaining methods specified bv 
shape classcan be inherited or defined by subclasses. Tables3and 
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4 contain information about the methods specified by line class. 
From these tables, we see that none of the methods specified by 
line class are required or chained, and each can be inherited by 
subclasses. Other than the methods required by shape class, 
rectangle class can either inherit or redefine the remaining nieth- 
ods specified by shape class, and inherit or redefine all the 
methods specified by line class. 

Polygon objects behave exactly the way we want rectangle 
objects to behave, with some exceptions. First, the insertdrag 
method for polygons does not constrain the number of points 
which can be inserted when new polygons are graphicallv de- 
fined, nor constrain the way edges connecting the points are 
connected. Rectanglescan not have more than fourpointsfactually, 
we use live points, hut the List one is an artificial point), and the 
Unesconnectinglhemmust|oinat right angles. Second,a polygon's 



d.iss' Rectangle class's updated procedure does not check for 
this, so how does it make sure rectangle objects are not resized in 
such a way that they become distorted 1 I o answer this quest ion, 
we have to look at what the update!) procedures of rectangle 
class's superclasses do (a production quality protocol description 
contains this type of information). The source code for line class 
and poly class is on the disk that accompanies this article, so you 
can examine their updated procedures in detail. Poly dass'S 
updated procedure just calls line class's update!) procedure, 
which detects bounding box value changes. It then calculates x- 
and y-scale values from the old and new bounding box values, 
and calls the resize!) procedure whose pointer is in the class 
structure of the object it is updating lor rectangle objects, the 
class structure pointer is recti lass, .md the resize procedure thai 
is called is rectangle class's resized procedure Here is the code 



New classes of objects are added to our CAD 

application program by adding an "insert" menu 

subitem for the new objects. 



individual points can be dragged and moved. We do not want to 
allow the points defining rectangles to be moved, since the 
rectangle will be deformed if its individual points are moved. 
Third, polygons can be rescaled in such a way that they are 
distorted, This happens if unequal x- and y-scale values are 
applied to the polygon's points. If the points defining a rectangle 
are scaled with unequal x-and v-scale values while it is rotated at 
an angle other than 0, 90, or 270 degrees, the rectangle will be 
distorted into a non-rectangular parallelogram. Because of these 
reasons, we need to define insertdrag and resize methods so we 
can constrain the points defining rectangles. We also need to 
disallow dragging and moving of our rectangle objects' indi- 
vidual points by setting pointers to the methods specified by line 
class 10 NULL. We can inherit all the remaining methods needed 
to implement rectangle class. To summarize, the methods we 
need to define are setupClass, setvaluc, getvalue, update, 
insertdrag, and resize. Having decided what methods to imple- 
ment, we can now declare rectangle class's procedures, initialize 
Its class structure (_rectClass|, and code its procedures. The 
source code file containing the implementation of rectangle class 
is in Listing 6. The following paragraphs describe the procedures. 

Rectangle class's setup! ) procedure works exactly like circle 
class's (and all of our other classes') setup procedures: it makes 
sure the rectClass structure is initialized, and then resolves in- 
heritance for any of its subclasses. Rectangle class defines onlv 
two procedures that can be inherited by subclasses, so only four 
lines of code are required to support subclass inheritance. 

Rectangle class's getvalue{), setvalue(), and updated proce- 
dures are extremely simple. They just call their superclass's 
getvalucd, setvaluef), and updated procedures. The atoms for 
rectangle objects are defined by line class, so rectangle class does 
not need tosetany values or return any, other than its class name. 
What if the bounding box for rectangles is changed by shape 



from line class's updated procedure which calls rectangle class's 
resized procedure ("lineC" is the class structure pointer for the 
object being updated): 



." 



cornei 



scale v 



. .0 I I sy := 1.0 I 







(void) rlmeC- 




bject. 




>minx,cpy 


■ . sy) ; 






(void) res 


r. ,cpy- 



>minx,cpy->miny.sx.sy) ; 

Rectangle class's resize method contains special case code to 
handle scaling of rectangles that are rotated at angles other than 
0, 90, or 270 degrees. Scaling rectangles rotated at angles other 
than these with unequal x- and j scale values causes them to 
become non-rectangular. You can observe this in our mini-CAD 
program by creating a rectangular polygon, rotating it, and then 
scaling it. To prevent this from happening, the resize!) procedure 
finds the angle of rotation of a rectangle by finding the angle of 
rotation of its original bottom edge. If the angle is 0, 90, or 270 
deques, the rectangle is resized using whatever scale values uei.' 
specified. Otherwise, both the x- and y-scale values are set equal 
to the smaller of the two, and the rectangle is then resized using 
the equal scale values. The resized rectangle is then moved so its 
center is located where il would have been if it had been resized 
using the unconstrained scale values. Although rectangle class 
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implements a resize() procedure, it capitalizes on the resize)) 
procedure ot its superclass by calling it to do the actual scaling 
transformation. Rectangle class's resi/et) procedure just imposes 
constraints on how rectangles .ire rescaled. 

The list of points defining a rectangle object is created in 
rectangle class's insertdragO procedure. This procedure obtains 
the initial point coordinates by creatinga drag rectangle from the 
pick point, and using dragDrawRect(> to process the drag inter- 
action with handleDragl). When handleDragO returns, the cor- 
ner coordinate- of the drag box are used to generate the list of 
points defining the rectangle 

That's basically all the code we have to write to implement 
rectangles, thanks to inheritance! We have one more task to 
perform before we can use ou r new objects: we need to add them 
to our mini-CAD program. This is the easy part. 

Adding New Classes to the CAD Program 

Neu l Kisses of objects are added to our CAD application 
program by adding an "insert" menu subitem for the new 
objects. This is done in the file menu.c. We need to include the 
new classes' public include files in menu.c, and deline three 
structures for each new class of objects. The three structures are 
an IntuiText structure containing the menu item name for the 
object, a miDataj structure containing the da ta sent to the menu 
item's pick event procedure, and a myMenuItemj structure 
containing the menu item's definition the three structure defi- 
nitions lor rectangles are 

static st: . rexc insTxtU = 

( 

,JAM2,2.1, NULL, "Rectangle", NULL >, 



static miDa' 
0, (void"JicectClass 

C myMenuIt 



ita : 



{ dragAndlnsert, 



. 



...... - v 

' *• ' .0,0,0,0, 

KMENABLEDIHIGHCOMP, 0, 

( AfTR) ct 10] .NULL, NULL, NULL, HENUNULL 

:on, IvoidM&insRectData } 
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experience repairing the Amiga Computer . 

Covering everything from basic theory of 
operation to our special tricks and tips sec- 
tion this video is sure to save you many 
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Conclusion 

This has been a long series of articles. We have explored 
several different topics, discussed techniques for implementing 
object-oriented CAD systems, and developed some useful soft- 
ware along the way. In Part 1, we developed ,i library of 2-DCAD 
transform procedures. In Part 2, we discussed techniques and 
developed procedures for attaching event handlers to Intuition 
input objects. In Part 3, we saw how to implement an object- 
oriented CAD system in "vanilla C", and in this final article, we 
saw how to useour object framework to create brand new objects 
forourCADprogram.Althoughourmini-CADprogramtsbyno 
means complete, it implements the core functionality found in all 
CAD systems. With a little work, you should be able to use the 
code which accompanies this article and the techniques We have 
discussed to turn our mini-CAD program into a complete object- 
oriented CAD system! Have fun! 







The listings and all necessary files for 

CAD Application Design Part 4 can be 

found on the AC'S TECH disk. 



\; 



After these definitions are added to menu.c, the program is 
recompiled and relinked, and voila!, our new objects can be put 

to work. Consider the significance of what we have just done. We 
added new objects tO our CAD application without modifying 
any of its code! Being able to extend an existing system without 
modifying its source code is a major benefit of object-oriented 
systems. 



Please write to 

Forest W. Arnold 

c/o AC'S TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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After months of refining code, squashing bugs, rewriting 
documentation, and creating attractive packing (or your program, 
you're finally ready to release your product to the Amiga-using public. 
Now \ on can dash oft .1 press release and starl sending review copies 
OUl to your favorite Amiga magazines, right? 

Admittedly, creating a press release is often the last thing on I 
programmer's mind. Some developers believe that a polished, well- 
designed piece of software should be enough to guarantee some press 
coverage While good software does happen to sell itself, a thought- 
fully written, timely delivered press release serves an important 
purpose, rhe press release is an important tool, a tool which can help 
you announce new products and get those products more media 
co\ erage A press release ..in be used in other instances as well, such 
as when you ship a major software update, drastically change : 
or when your company undergoes a major change in management or 
ownership. 

Why Should I Use a Press Release? 

A good way (o understand the importance of a press release is in 
look at how the media uses. them. In the case of the Amiga press, a 
press release alerts them to new items, which are assigned lo .1 New 
Products Editor This editor is often the first person lo look al VOW 
product I sing your press relea>e as reliable background informalion. 
this editor writes a short description of your product for the New 
Products section. From hen?, your program— with press release 
attached- -travels to another editor, usuallv a Review Editor or 
AsMKi.ite Editor Ihis person looks at your product and reads rail 
press release, using both to decide whether to assign the produ 
staff editor or freelance writer for review, or to hold the product for 
later examination. 

At each of Ibex- stage>. the value of a press Kle«M cannot be 
Overstated, Ihe New Products editor draws information from your 
release to write a shorl description of your product, the Associate 
editor uses Ihe press release to help gauge how important your 
product is and how it should be reviewed; and finally, the actual 
reviewer of the product often uses a press ideas, to become familiar 
Wtth the main tealures of your product. If your press release is filled 
With spelling and grammatical errors, or lists inconect information, it 
makes the job of each one of these individuals more lime-consuming 
Kememher that journalists are always on a deadline: time spent on the 
phone clarity mg a contusmg or ambiguous pres, release translates into 
less tune lor the reviewer to spend evaluating your product It Ihe 
editor can't reach the person listed as a contact on your press release 
(or if no contact is listed), your product might be put aside until 
questions can lv answered and ambiguities clanh.-d Youi press 
release is often the only communication an editor might see from your 
company. m< it s important to tn.ike.i good impression 



Is There a Right Way to Write 
a Press Release? 

Although there isn't a set 01 rules cast in Stone someplace on how 
lo write a good press release, here are some generally accepted 
guidelines dealing with the bask structure and lavout of a press 
release: 

1 I se good quality, lettersi/e(»5 , n ) paper. Double-space all text, 
using just one column on each page. Set top, bottom, left, and right 
margins al 1' 

2. Put your company logo, add ress. and telephone number in the 
upper left comer on the first page rj| the release Try to limit press 
releases lo two pages, and print on onlv one side of each page. 

1 In Ihe upper right comer of the first page, parallel to your company 
inform anon, list a contact name and phone number. This should be a 
person an editor can contact for clarification or questions on informa- 
tion included in your press release Make sure the person listed is 
aware of the press release and can accurately respond to any inquiries 

I I K a headline to quickly convey the main content of your press 
release Center the headline and place it directly over the body text of 
your press release on the first page. 

5 Place the date at which the information in Ihe press release can be 
used in the upper left comer of the first page, between your company 
information and the headline. You'll normally want to put "For 
Immediate Release" in thus spot, unless ymi want the Information 
released ,1! .1 cert. 1 in date In that case, use this format: "For September 
26 Release** Keep in mind that most magazines are published 
monthly, so alter release dales accordingly. 

6. On the first line of your main text, print the city and stale from 
which the release is originating in capital letters, followed by a release 
date Use this format: 'FALL RIVER, MASSACHUSETTS August 3rd, 

1992 — " 

7. Avoid using excessive computer jargon. Although most editors are 
exceptionally familiar with computet terms, take the tune to ad- 
equately explain uncommon acronyms and other rarely used lan- 
guage 

- it your release announces a new product, be sure to include an 

extensive list ol program requirements This information should 
usually be saved for the last p ar agr a ph ol your press release 
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9. If more than one page, put the word "MORE," centered, on the 

bottom of the first page. Signify the end of the press release by placing 
the symbols "•##" or the number "30" at the bottom of the List page 
Output the press release to a high -quality pnnter, preferably an ink-jet 
or laser. (The sample press release on p. 79 use-. all the suggestions 
listed above.) 

Again, these are only rough guidelines — as long as youi re l eas e 

is short (two pages or less), tersely written, and supplies all the 
necessary information, you can deviate somewhat from this format 
Once you've chosen the physical layout of your press release, it's time 
to look at what goes into a press release What follows are some 
general suggestions on writing a press release to announce ■ new 
product. 

Guidelines for Grammarians 

If you're shipping a new product, avoid the temptation to make 
your press release a giant feature list. Think about what makes your 
product differ from competitive products, and concentrate on those. 
For example, if your new product is a word processor, don't spend 
valuable space discussing its word-wrap feature and ability to open 
and save documents — focus on what makes your product unique, 
perhaps its ability to read a document aloud Orexteittlvc -\Ke<< 
support. 

After you've decided what you're going to include, you can begin 
writing your release It's important at this point to mention the twin 
bugbears facing ever)' budding writer of press re! eases— grammar and 
spelling. Even good, experienced writers occasionally commit some 
errors, so keep a dictionary handy and use a spell checker often. Manv 
of the books listed a! the end of ihis article can be very helpful with 
grammar, particularly Vie Elements of Style, by Strunk and White, and 
Tlie Chicago Manual of Style, by the University of Chicago press. T7w 
Associated Press Slylebook and Libel Manual is another good text, used by 
journalists themselves to find rules on spelling, punctuation, and 
grammar. 

When writing your press release, it's important lo write in the 
active voice as opposed to the passive voice. Tor example, "AcmeSoft's 
C*» Professional supports AmigaDQS 2.0" is m the active \ 
"AmigaDOS 2.0 is supported by AcmeSoft's C- * Professional" is in 
the OSMivt voke Write by "doing" (active) instead of "showing 
(passive). Using the active voice in your press release shortens 
sentences and makes, for easier reading You'll also want to writl 
press release in what journalists call the "inverted pyramid 1 ' writing 
style. Visualize a real pyramid Hipped upside down — the wide, thick 
base of the pyramid is at the top. As you move lower, the pyramid gets 
smaller and smaller, eventually tapering off to a tiny point |ust like 
this topsy-turvy pyramid, you'll want to put the "biggest," most 
important ideas at the top, or beginning of your press release, followed 
by the next most important, and so on, until your release draws to a 
close. Used by print journalists worldwide, this form of writing 
manages to pack the most important information into as small •' space 
as possible. The first sentence of your press release, called a "lead." 
should contain the most important information you are trying to 
convey. For example, if your compam |u a new gome, your 

lead would look so met hin g like this "('.amesoft has released Midway 
Monsters, a new football game featuring roloscoped animation of real 
players, for the Amiga computer." In just one sentence, you've 
introduced your company, announced a new product, stated B unique 
feature of that product, and mentioned which computer that product 
operates on If you aren't very familiar with this style of writing, jusi 
drop by your local library or bookstore and ask for books on 
newswriting or print journalism 



Other Points to Remember 

When releasing new product Information to I publication, it's a 
good idea to send two review copies oi your product — sturdily 
enclosed within adequate packing material— along with your press 
release Win two copies? One copy stays with the magazine's editorial 
staff, while the other is often mailed out to a freelance authoi tor 
review. For press releases which don't involve new products, a large 9 
« 1 1 envelope with the press release (and possibly a business card) 
will suffice. 

As bad as sending a poorly crafted press release to the media can 
be, sending too many press releases can do even more damage |ust as 
in the Aesop's Fable where the boy cries "wolf" one too manv times, 
flooding an editor's desk with press releases of marginal news- 
worthiness can result in a truly important announcement of yours 
being overlooked, A press release dealing with such things as minor 
personnel changes, new packaging for your product, or the forthcom- 
ing marriage of your lead programmer may be very important lo VOU, 
but of little interest to the Amiga community at large Limit VOU! prCSS 
releases to new product announcements, significant product updates, 
major organizational changes, and other information of equal 
importance. 

Finally, it's always wise to send your press kit addressed to a 
specific individual as opposed to a generic job title. Addressing your 
communication specifically to one Indh Idual Im p roves the chances of 
your product getting noticed. If necessary, call the magazine before- 
hand and find out the full name of the poison in question (be sure to 
get the correct spelling, too). It does work, just think how you feel 
when you receive a letter addressed to "current resident," and you'll 
see why this step is effective 

I hose suggestions obviously cannot replace a structured course 
on public relations writing. If you're new to writing press releaser, 
several of the ted at the end ot this article are excellent reading 

material Taking a course on public relations or persuasive writing at a 
local community college can also be helpful. Ob* iously. a press release 
Can't work miracles. Asa software developer, your first priority should 
be to > reate a solid, reliable program that people would want to 
purchase. However, in an increasingly competitive Amiga market, a 
well-written press release can help tip the scales in your favor. 

Suggested Raiding: 

The Chicago Manual of Style, I3thed University ot Chicago Tress. 
Chicago, 1982. ISBN 0-226^ 10390-0. $37.50 

The Elements of Style. 3rd ed William Strunk |r. and E.B. White. 
Macmillan Publishing. New York, 1979. ISBN 0-02418200-1 ^ Ms 

Biomen Writers Handbook, 3rd ed Brusaw, Aired. Oliver St Martin's 

Press, New York, 1987. ISBN O-3I2-10958-X J19 

Hem R,-p<"*i"S and Writing, 3rd ed Brooks, Kennedy, Moen, Ranly. Si 
Martin's Press, New York, 1988. ISBN 0-312-00279-3 $23.95 

Hots (i> IVnii-tf Dynamic ' ' -■ Communication Workshop, 

217 East 85th Street, New York. NY 10028. IMft> 767-9590, $8.00 

Tlie Associated Pte*$ Sti/lebock and libel Manual. Norm (.oldstein I d 
Addison-Weslev Publishing. New York. 1992 ISBN 0-201-56760-1. 
$11.95 



The following page ls - 1 sample of a press release 
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AC'S TECH 



Contact: Jim Acme 
508-678-4800. ext. 123 



A.S.I. 

AcmcSoft. Inc 

1234 Serendipity Drive, Suite 300 

Fall River. MA 02720-7160 

508-678-4800 



FOR IMMEDIATE RELEASE 



AcmeSoft Releases C++ Professional 
Compiler for the Amiga 

FALL RIVER. MASSACHUSETTS: August 3rd. 1992 — AcmeSoft Inc. (ASI) has just released the C++ 
Professional Compiler (C++ Pro) for the Amiga computer. C++ Pro is a powerful program development 
system which brings the latest advances in object-oriented programming technology to Amiga software 
developers. 

"ASI's C++ Pro for the Amiga has cut our program development time by 30%." says Gary Buss, lead 
programmer for Penguin Software. "C++ Pro gives our programmers a powerful development s\ stem for 
creating the best in Amiga game software." 

ASI*s C++ Pro offers fast compile speed and full support for the new AmigaDOS 2.0 "look and feel." C++ 
Pro also includes: 

• Acme Debugger • Acme Compiler • Full support for ANSI C 

ASI's C++ Pro has a suggested retail price of $149.99 (S169.99 CDN) and operates on all Amiga models 
with 1 MB of RAM and Kickstan 2.0 or higher. A hard drive and color monitor arc recommended. ASI is a 
diversified software company that develops and publishes Amiga productivity software worldwide. 



-30- 
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To Order Calll -800-231 "0359 

Illinois Orders Call 1-708-893-9614 

For Product Information or Tech Support Call 1-708-893-7464 

FAX Number 1-708-893-2970 






PRODUCTIVITY 



:i 






.: 



AGFA Type Collect 
Ami-Back. 
AMOS 3D 
AMOS Compter 
AMOS Creator 
Arexx. 
ArtDeptPro Ver2. 
Audto Master IV 
Audi lion 4 
BAD 

Baud Bandit , 

Buddy Sys A Dos 2 
Buddy Sys; Imagine . 

Cygus Ed Pro 

Deluxe PainO 

Deluxe Painl4 

Design Works 

Directory Opus 

Disney Animation 

Final Copy 1.3 

Fractal Pro 5.0 

HomeFronl2.0 

Hot Links 

Image Finder 

Imagine 2.0 

Imagine Companion 

UtticeC 

LockPtck 

MigraphOCR 

Page SbeamS 

Pagesetierll 

Patch Meister 

Pnasar 

Pixel 3D 2.0 

Pro Fills 2.0 

Project D 2.0 

Pro Page 3.0 

Pro-write 

Quatterback5 

Quarterback Tools .. 

Quick Write 

Scape Maker 

Scenery Animator ... 

Super Jam 

Surface Master 

Turbo Sitver/Tertain 

Turbo Text 

TV Text Pro 

Vista Pro 2.0 



CALL 

47.95 

41.95 

41 95 

59 95 

29 95 

179 95 

59 95 

59 95 

29.95 

„ 29 95 

.. 29.95 

.29.95 

59 95 

.. 59.95 

107.95 

.. 74.95 

.. 35.95 

.77.95 

59 95 

.89 95 

59.95 

59.95 

.. 39.00 

269 95 

.. 23.95 

193 00 

.. 35 95 

249.95 

179.00 

.77 95 

59 95 

53 95 

... 77.95 

... 29 95 

... 35.95 

179.95 

.94.95 

... CALL 

.48 95 

... 44.95 

.23 95 

...59.95 

.89 95 

...20.95 

... 59 95 

.59 95 

.99 95 

... 59.9^ 



IVS.VECTOR 



68030 2S. 33. 40 MHZ. MEMORY UP TO 32MB 
TRUMPCARD PRO CONTROLLER BUILT-IN. 
IN 68000 MODE CAN ACCESS HARD DRIVE 
ANO UP TO 8MB CALL FOR PRICE 



L 



- 
















(:!!;!; 



A500 HARD DRIVE 
CONTROLLERS 



HI I i! 
I I 



GVP HO 8*0 /52MB 

TRUMP CARD 500 AT... 
TRUMP CARO CLASSIC 

TRUMP CARD PRO 

IVS GRAND SLAM 

DATA FLYER 500 SCSI.. 

.. ;:■■-;■-■:.: : : ■ 



509.00 
229.00 

169.00 
229.00 
289.00 

149 00 



;; 
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A2000 HARD DRIVE 
CONTROLLERS 



IVS GRAND SLAM 

TRUMP CARD CLASSIC 

TRUMP CARD PRO 

GVP HC 8/0 120MB 



GVP ACCELERATORS 



25MH21MBRAM 

40 MHZ 4MB RAM 

50MHZ4MBRAM 

4MB SIMM 32 MODULES 



itlliiilii l ii 



SYQUEST 



;;:! 



44 MB SYQUEST INTERNAL 
88 MB SYQUEST INTERNAL 

44MB CARTRIDGES 

88MB CARTRIDGES 

EXTERNAL CASE W/PS 




MICE 



ALFA DATA OPTICAL MOUSE . 
ALFA DATA UPGRADE MOUSE 

GOLDEN IMAGE GI-600N 

GOLDEN IMAGE / DPA1NT 2 .... 
GOLDEN IMAGE OPTICAL MOUSE 52 
JIN MOUSE 23 



39 
27 
31 
42 



Ei»i • 



DE-INTERLACERS 



COMMODORE A2320 239.00 

MICROWAY FUCKER FIXER 239.00 

ICD FLICKER FREE 249.00 

— -=■■_-_---«■ 






KICKSTART 
SELECTORS 



DKBMULTISTARTII 

KICKSTART SELECTOR 



50 00 
33 00 



rrrrr. 



-—-—. 



SAFESKINS 



AFESKIN A500 .. 
AFESKIN A2000 
AFESKIN A300O 



12.00 
1200 
1200 



GENLOCKS 



,„ MINI GEN , 

Hi ROC GEN PLUS 



189 00 
34500 



______ 



DRIVES 



RAM 



AIR DRIVE EXTERNAL 

AIR DRIVE A2000 INTERNAL 
AIR DRIVE A3000 INTERNAL 

ALFA DATA EXTERNAL 

MASTER 3A EXTERNAL 

ROCTEC EXTERNAL 

ROCTEC A500 INTERNAL 



80 00 
73 00 
89.00 
75 00 
82 00 
82 00 
79.00 



1 256 X4 DRAM 

1MBX1 DRAM 

1X8 SIMMS 

1X4 ZIPPSIA3000) 



CALL 
CALL 
CALL 
CALL 






; 



AMIGA 2.04 UPGRADE 



S84.95 



.: :::: 
_— 
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NEW PRODUCTS 

ARRIVING DAILY. 

CALL FOR PRICING 

AND 

AVAILABILITY 






FD Software 

120 South Ridge 

Bloomingdale, IL 60108 

Hours M-F11-7 Sal 10-6 



Shipping Into: Sh.pp.no 14 SO pa' ofdar in Contmenial U S . Ships via UPS 
Ground. COD Add $4 50.CH (or Express shipping rales. Alaska. Hawaii, 
Puerto Rico. Canada. Ma*. Poreon shipping a«tra. Oversize orders ship at 
cu-r.ni UPS Rates Return & Refund Pottcy: Detective products raplaced 
within 30 days ol purchase 1 S% restocking charge on All retu'nad non- 
Oofectiva merchandise. Other Policial: VISA/MASTERCARD/DISCOVER- 
No Surcharge "Imois Res-denis add 6.75% SaJas Tax Walkm Traffic 
Welcome . Store prices may vary Prats Subject lo Change W.thout Nobce 



I i : ; - 
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Circle ID! on Reader Service card 



AC Order Form! 



Name_ 
Address 
City 




State 



ZIP 



Charge my Visa 
Expiration Dale 



MC * 



Signature . 



Please circle lo indicate this is a New Subscription or a Renewal 



PBOW«IKW£SSREQUIflE0 .i"0'OeftoeiB»»»4ia 
guawter r ojT cflv an ia*ge Put*c Do"-ai' Solh»jri 
OMmtw^lurncMiBKklisuvonWfs areilhppMbr 
Un.tMP#ef Service UPS'eaii'?5"ii»Ppaek*g«t» 

J«V«l«JtOJl"»«l*»MS'0'tO'((!Cl«tT.t>> 

PAVMEHTS8VCHECK A 1 :ii("--'li'n»eeO»efieckO' 
rf«ro|0'd*""utlE*i«U5V"OiO'a«non4U S Mi* 





Save over 43% 


",., 




1 "fii ; i»i s r ' 


AmazhiK < amfmlOiji .il .1 Wing* 111 OV« 520.00 ofl IUC ttTOSlanfl price! rfntrifpi Surtaw SM0O 




On Knu 

SufwrSub! 


Save over 45% ussroo 

l-'i llhlj ishjimoI tlTOZing Gompuiing PUIS lCC44W^(uO« I inadi Me\Jcn SS* Of] 

2 Product Gunk-, .i year" v saving* <>i uvci S„«00ofl ihc m« w .. ■.., price' ,.,, surtaci Sfrion 




Tivn Voitrs 


Sove ove/- 56% 

j i month!) issues irf ihc numbci one resource 10 the Commodote Amiga, Amazing 
i (imputing .H j ravings of ova 553.80 off the newsstand price* 


i s mi oa 

l*IWT) nn Inur^n unlet* 

. M tin- fiequrn.-) > 




t'HllIIH^.' 




J ii D Years 

qfAC 
SufwrSub! 


Save over 56% « s« 

24 montlily issue* of Amazing Computing I'M s « '•' »"/i"".i lnonynoftindsBUBleo 
i Product Guide*! \ savings al ovvi $75,60 ofl Ihc newwaand price! available n ihta ffcquvnci » 




Obm lew 


P1USJ \' lltU/iMlGA 








<4C'» ITCMF 


* 
• quunerl) Ismih •>! il»- find Amiga technical reference magazine wall «!i-K' 







Please circle any additional choices below: ,/>,.,,„ s f „ „,„/ / ,„„ v „ ah mail ,,„„ omffaHrwi rgqn«u 

Amazing Computing Back Issues S5.00 each US. S6 00 each Canada and Mexico. 

S7 00 each Foreign Surface Please list issue(s) Subscripts. S 

Amazing Computing Back Issue Volumes: 



Volume 1 -S1 9.95* Volume 2. 3. 4, 5. or 6-S29.95* each 

"All volume ardors must include postage and handling charges: $4 00 each set US. $750 

each set Canada and Mexico and SiO 00 oach sot lor foreign surface orders Air mail rales available 

\C. TECHmMIGA Single fesuttjusl $14.95! vi Khwi. vis. v13.vn.v2io.v2 2 

\ iiluiiu- One complete— S45.tH>! (A» Four *wes) 

Freely Distributable Software - Subscriber Special (yea. even the new ones!) 
1 lo 9 disks $6 00 oach 

10 lo 49 disks S5.00 oach 

SO lo 99 disks 54.00 each 

100 or more disks S3 00 each 

$7.00 each lor non subscribers (three disk minimum on all foreign orders) 

*C«1 S<ahw ft Lrtl-igi VJ B A V3 9 AC«! Sorts A Ifng* V4 ) A VI -I 

So-.™»Li»ll"u«V4 5AV«8 AC«« StKirc* A UtffiQi V* ! h V B 

Sauna A UMino* V« 9 ACW Soux* A LMtyp V* 10A V4 11 

Sarai A l.»Wtg» V4 i;i vbi AC«B Sou"* A l«i™ VS J A 1 3 

Sam» A U»1«ig» V5 * A VS 5 AC»I0 Souum A lnhng* V$ 6 A 5 » 

Sou<t. A l*n»o» V5 B S 9 A S «0 AC»I? Sout* A UM*>0» VS 1 1 . 5 1 3 A 6 I 

Sauna A Latog* V6 ? A 6 1 AC»t* Scuira A Litlmgk VB*. AOS 

ACllS Souroi A l-*r*oi V6 6 07. SB A69 ACUfi Sown A Inbngi VftlQ 6 11.6 '. 

Please Iim youi Freelj Reclteuibuiable Software selections lielon 

A C Disks 

AMICUS 

(mimhvr\ I ihrtnifih 26) 

Fred Fish Disks 



Back Issues: S 



AnuodogonDfaJtj 1^" 

AC»r 
AC«9 
AC*1I 

A." ■«■■. 



AC'S TECH $ 



PDS Disks 



Complete Today, or telephone 1-800-345-3360 now! 

You may FAX your ordev to J-SOfl-oVS-oOO;? 
Please complete this form and mail with check, money order or credi! card information to: 

Pxw&o aaow 4 lo 6 weeks lo» defcvofy ol suOscnpiions « US 



Total: S 

imiI>K'H in uppthrlMe vili - bis J 



P.i.M. Publications. Inc. 

P.O. Box 2140 

Fall River, MA 02722-0869 



Quarterback 5j0 

The Next Generation In Backup Software 



Quarterback 5.8 C 19*)2 Central Coast Software 



Quarterback 



Backup in progress. 



Mho. t 



Bum u, it it..) 11 

QDF2: Ready 
ElDf3: Ready 

Conpleted: Ay. 



Files: 

Bytes: 

TaffledL 



25 

178,568 



Files: 
Bytes: 



559 
•1,599,613 



Q 




/- Backup started Feb 11, 1992 at 18:55:82 RH 
CDSystm?.0 

f. 

D RddBuf fers 

Jflrc 

DRsslon 

D Avail 

*JBindOrivers 

J: Break 

( li.,.H)r I. ...kl'i i 

ConClip 

Date 
Delete 

Dir 

i skChange 

OiskOoctor 

DiskSalv 

Ed 

Edit 

Eva I 

Execute 

F i lenote 

IconX 

Info 

Ins 1a 1 1 

IPrefs 



-/ 





• The fastest haekup inn! an/living program on the ton/go! 

• Supports, up to four Happy drives /<>/ backup and restore 

• \tyvmlegrvted streaming tape support 

• \nr 'compression'' option for backups 

• Optional password protection, with encrt/pthn. for data 
security 

• Full tape control for retention, erase and 'rewinding 

• Mew Interrogator, " retrieves device information from 
SCSI devices 

• Capable of complete, suMirectory-only, or selected-files 
backup and restore 

• unproved wild card and pattern matching, for fust ami 

easy selective archiving 

• Restores all date and lime stamps, fffirnoles, and 
protection bits "" fibs ami directories 

• Supports both hard and soft links 

• Full macro and AREXX support 

• lull Workbench 2.0 compatibility 

• Improved user interface, with Workbench 2,0 style .:■/>' 
appearance 

• V<m« more features'. 



Thousands of people rely on Quarterback 
for their backup and archival needs. Now. 
with Quarterback 5.0. there is even more 
reason to do so. Greater speed, even more 
features, and proven reliability. And a 
new "3-D" user interlace puts these 
pi 'Wilful capabilities at your finger tips. 
With features like these, it is no wonder 
that Quarterback is the best selling 
backup program for the Amiga. Would 
you trust your data with anything less? 




Central Coast Software 

\l>ttis<i-n<» Sete Ihmzu'is SotfuwV, hie 

2()6 Wild Basin Rood. Suite 109, 

Austin. Texas 7S7t»i 
(512) .128-6650 • PAX Cil2) :'.2X-1925 



C-tl» 103 o" R*»Of Service twO 



